web/README.md

240 lines
8.9 KiB
Markdown
Raw Normal View History

2019-09-30 15:37:14 +03:00
# Jekyll Theme Chirpy
[![Build Status](https://travis-ci.com/cotes2020/jekyll-theme-chirpy.svg?branch=master)](https://travis-ci.com/cotes2020/jekyll-theme-chirpy)
[![GitHub license](https://img.shields.io/github/license/cotes2020/jekyll-theme-chirpy.svg)](https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/LICENSE)
2020-01-04 12:05:41 +03:00
[![996.icu](https://img.shields.io/badge/link-996.icu-%23FF4D5B.svg)](https://996.icu)
Language: English | [简体中文](docs/README_zh-CN.md)
2020-01-04 12:05:41 +03:00
A minimal, portfolio, sidebar, bootstrap Jekyll theme with responsive web design and focuses on text exhibition. It will help you easily record, manage and share your knowledge and experience.
2019-09-30 15:37:14 +03:00
You will get the following features:
2019-09-30 15:37:14 +03:00
2020-01-04 12:05:41 +03:00
* Auto Dark Mode
2019-12-31 20:24:54 +03:00
* Posts' Last Modified Date
2019-09-30 15:37:14 +03:00
* Table of Contents
* Automatically Recommend Related Posts
2019-09-30 15:37:14 +03:00
* Syntax highlighting
* Two Level Categories
* Search
2019-12-31 20:24:54 +03:00
* Atom Feeds
* Disqus Comments
2019-09-30 15:37:14 +03:00
* Google Analytics
2019-12-31 20:24:54 +03:00
* GA Pageviews (Advanced)
* SEO Tag
* Performance Optimization
2019-09-30 15:37:14 +03:00
[**Live Demo** »](https://chirpy.cotes.info)
![devices-mockup](https://raw.githubusercontent.com/cotes2020/jekyll-theme-chirpy/master/assets/img/sample/devices-mockup.png)
## Table of Contents
2020-01-14 14:57:10 +03:00
* [Installing](#installing)
* [Usage](#usage)
* [Contributing](#contributing)
* [Credits](#credits)
* [Support](#support)
* [License](#license)
2019-09-30 15:37:14 +03:00
2020-01-14 14:57:10 +03:00
## Installing
2019-09-30 15:37:14 +03:00
### Prerequisites
2019-09-30 15:37:14 +03:00
Follow the [Jekyll Docs](https://jekyllrb.com/docs/installation/) to complete the installtion of basic environment (Ruby, RubyGem, Bundler and Jekyll). In order to use the script tools to save time, we also need to install [Python](https://www.python.org/downloads/)(version 3.5 or abover) and [ruamel.yaml](https://pypi.org/project/ruamel.yaml/).
2019-09-30 15:37:14 +03:00
In addition, if your machine is running Debian or macOS, make sure you have the [GNU coreutils](https://www.gnu.org/software/coreutils/) installed. Otherwise, get it by:
2019-11-16 18:12:26 +03:00
* Debian
2019-11-16 18:12:26 +03:00
```console
$ sudo apt-get install coreutils
```
* macOS
```console
$ brew install coreutils
```
2020-01-14 14:57:10 +03:00
### Jekyll Plugins
[Fork **Chirpy** from GitHub](https://github.com/cotes2020/jekyll-theme-chirpy/fork), then clone your forked repo to local:
```console
$ git clone git@github.com:USER/jekyll-theme-chirpy.git
```
replace the `USER` above to your GitHub username.
The first time you run or build the project on your machine, perform the installation of Jekyll plugins. Go to the root of repo and run:
2019-11-16 18:12:26 +03:00
```terminal
2019-09-30 15:37:14 +03:00
$ bundle install
```
`bundle` will automatically install all the dependent Jekyll Plugins that listed in the `Gemfile`.
2019-11-16 18:12:26 +03:00
## Usage
2019-11-16 18:12:26 +03:00
### Directory Structure
2019-11-16 18:12:26 +03:00
The main files and related brief introductions are listed below.
```sh
jekyll-theme-chirpy/
├── _data
├── _includes
├── _layouts
├── _posts # posts stay here
├── _scripts
2019-12-24 15:33:13 +03:00
│ └── travis # CI stuff, remove it
2020-01-01 20:21:43 +03:00
├── .travis.yml # remove this, too
2020-01-04 12:05:41 +03:00
├── .github # remove it
2019-11-16 18:12:26 +03:00
├── assets
├── tabs
│   └── about.md # the ABOUT page
├── .gitignore
├── 404.html
├── Gemfile
├── LICENSE
├── README.md
├── _config.yml # configuration file
2020-01-01 20:21:43 +03:00
├── tools # script tools
├── docs
2019-11-16 18:12:26 +03:00
├── feed.xml
├── index.html
├── robots.txt
└── sitemap.xml
```
2020-01-04 12:05:41 +03:00
As mentioned above, some files or directories should be removed from your repo:
- .travis.yml
- .github
- _scripts/travis
### Customization
2019-11-16 18:12:26 +03:00
Basically, go to `_config.yml` and customize the variables as needed, some of them are typical options:
2019-11-16 18:12:26 +03:00
2020-01-04 12:05:41 +03:00
* Avatar
`avatar` defines the source image location. The sample image is `/assets/img/sample/avatar.jpg`. It should be replaced by your own one. Notice that a huge image file will increase the load time of your site, so keep your avatar size as samll as possible(may be *<https://tinypng.com/>* will help).
2019-11-16 18:12:26 +03:00
2020-01-04 12:05:41 +03:00
* TimeZone
2019-09-30 15:37:14 +03:00
2020-01-04 12:05:41 +03:00
To ensure that the posts' release date matches the city you live in, please modify the field `timezone` correctly. A list of all available values can be found on [TimezoneConverter](http://www.timezoneconverter.com/cgi-bin/findzone/findzone) or [Wikipedia](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
2019-11-16 18:12:26 +03:00
2019-11-18 17:36:22 +03:00
### Run Locally
2019-11-16 18:12:26 +03:00
You may want to preview the site before publishing, so just run the script tool:
```terminal
2020-01-01 20:21:43 +03:00
$ bash tools/run.sh
2019-09-30 15:37:14 +03:00
```
2019-11-16 18:12:26 +03:00
Open a modern brower and visit at <http://localhost:4000>.
2019-11-18 17:36:22 +03:00
Few days later, you may find that the file modification(e.g. edits to a post) does not refresh in real time by using `run.sh`. Don't worry, the advanced option `-r` (or `--realtime`) will solve this problem, but it requires [**fswatch**](http://emcrisostomo.github.io/fswatch/) to be installed on your machine. Type `-h` for more information.
2019-11-18 17:36:22 +03:00
2019-11-16 18:12:26 +03:00
### Deploying to GitHub Pages
2020-01-14 14:57:10 +03:00
Before the deployment begins, ensure the `url` in file `_config.yml` has been set to `https://<username>.github.io`(or the custom domain, if you have. e.g. `https://yourdomain.com`). What's more, if you prefer to the [Project site](https://help.github.com/en/github/working-with-github-pages/about-github-pages#types-of-github-pages-sites), change `baseurl` of file `_config.yml` to your project name, starting with a slash. e.g. `/project`.
2019-11-16 18:12:26 +03:00
#### Option 1: Built by GitHub Pages
2020-01-04 12:05:41 +03:00
By deploying the site in this way, you're allowed to push the source code directly to the remote.
> **Note**: If you want to use any third-party Jekyll plugins that not in [this list](https://pages.github.com/versions/), stop reading the current approach and go to [*Option 2: Build locally*](#option-2-build-locally).
2019-11-16 18:12:26 +03:00
2020-01-04 12:05:41 +03:00
**1**. Rename the repository to:
2019-11-16 18:12:26 +03:00
2020-01-04 12:05:41 +03:00
|Site Type | Repo's Name|
|:---|:---|
|User or Organization | `<username>.github.io`|
|Project| any one except `<username>.github.io`, let's say `project`|
2019-11-16 18:12:26 +03:00
2020-01-04 12:05:41 +03:00
**2**. Commit the changes of the repo first, then run the initialization script:
2019-11-16 18:12:26 +03:00
```terminal
2020-01-01 20:21:43 +03:00
$ bash tools/init.sh
2019-11-16 18:12:26 +03:00
```
>**Note**: The *Recent Update* requires the posts' latest git-log date, so make sure the changes in `_posts` have been committed before running this command.
2020-01-04 12:05:41 +03:00
it will automatically generates the *Latest Modified Date* and *Categories / Tags* page for the posts.
2019-11-16 18:12:26 +03:00
2020-01-04 12:05:41 +03:00
**3**. Push the changes to `origin/master` then go to GitHub website and enable GitHub Pages service for the repo.
2019-11-16 18:12:26 +03:00
2020-01-04 12:05:41 +03:00
**4**. Check it out:
|Site Type | Site URL |
|:---|:---|
|User or Organization | `https://<username>.github.io/`|
|Project| `https://<username>.github.io/project/`|
2019-11-16 18:12:26 +03:00
2019-11-18 17:36:22 +03:00
#### Option 2: Build Locally
2019-11-16 18:12:26 +03:00
2020-01-04 12:05:41 +03:00
For security reasons, GitHub Pages runs on `safe` mode, which means the third-party Jekyll plugins or custom scripts won't work. If you want to use any another plugins that not in the [whitelist](https://pages.github.com/versions/), **you have to generate the site locally rather than on GitHub Pages**.
**1**. Browse to GitHub website, create a brand new repo named:
|Site Type | Repo's Name|
|:---|:---|
|User or Organization | `<username>.github.io`|
|Project| any one except `<username>.github.io`, let's say `project`|
2019-11-16 18:12:26 +03:00
2020-01-04 12:05:41 +03:00
and clone it.
2019-11-16 18:12:26 +03:00
2020-01-04 12:05:41 +03:00
**2**. In the root of the source project, build your site by:
2019-11-16 18:12:26 +03:00
```console
2020-01-04 12:05:41 +03:00
$ bash tools/build.sh -d /path/to/local/project/
2019-11-16 18:12:26 +03:00
```
2020-01-04 12:05:41 +03:00
The generated static files will be placed in the root of `/path/to/local/project`. Commit and push the changes to the `master` branch on GitHub.
**3**. Go to GitHub website and enable Pages service for the new repository.
2019-11-16 18:12:26 +03:00
2020-01-04 12:05:41 +03:00
**4**. Visit at:
|Site Type | Site URL |
|:---|:---|
|User or Organization | `https://<username>.github.io/`|
|Project| `https://<username>.github.io/project/`|
and enjoy!
2019-09-30 15:37:14 +03:00
### Documentation
For more details and the better reading experience, please check out the [tutorial in demo site](https://chirpy.cotes.info/categories/tutorial/). In the meanwhile, a copy of the tutorial is also available on the [Wiki](https://github.com/cotes2020/jekyll-theme-chirpy/wiki).
## Contributing
The old saying: "Tow heads are better than one. Five heads are better than two." So, welcome to report bugs, improve code quality or submit a new feature. For more information, see [contributing guidelines](.github/CONTRIBUTING.md).
## Credits
2019-09-30 15:37:14 +03:00
This theme is mainly built with [Jekyll](https://jekyllrb.com/) ecosystem, [Bootstrap](https://getbootstrap.com/), [Font Awesome](https://fontawesome.com/) and some other wonderful tools(their copyright information can be found in the relevant files).
2019-11-05 17:14:02 +03:00
:tada:Thanks to all the volunteers who contributed to this project, their github ID is on [this list](https://github.com/cotes2020/jekyll-theme-chirpy/graphs/contributors). Also, I won't forget the guys who submitted the issues(or unmerged PR), they reported bugs, shared ideas or inspired me to write more readable documentation.
2020-01-04 12:05:41 +03:00
## Support
2020-01-04 12:05:41 +03:00
If you enjoy this theme or find it helpful, please consider becoming my sponsor, I'd really appreciate it! Click the button <kbd>:heart:Sponsor</kbd> at the top of the [Home Page](https://github.com/cotes2020/jekyll-theme-chirpy) and choose a link that suits you to donate. This will encourage me and help me maintain this project.
2019-09-30 15:37:14 +03:00
## License
This work is published under [MIT](https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/LICENSE) License.