asandikci.com/web
1
0
Fork 0
Code Issues 5 Pull requests Projects Releases Packages Wiki Activity Actions

Update docs for v2.5

Browse source
This commit is contained in:
Cotes Chung 2020-08-03 02:25:40 +08:00
parent 1c3c22bb68
commit adff74b27b
4 changed files with 210 additions and 393 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

195
README.md
View file

@ -13,7 +13,7 @@ A minimal, sidebar, responsive web design Jekyll theme, focusing on text present
## Table of Contents
* [Features](#features)
* [Installing](#installing)
* [Installation](#installation)
* [Usage](#usage)
* [Contributing](#contributing)
* [Credits](#credits)
@ -37,13 +37,28 @@ A minimal, sidebar, responsive web design Jekyll theme, focusing on text present
* GA Pageviews reporting (Advanced)
* SEO and Performance Optimization
## Installing
### Prerequisites
## Installation
Follow the [Jekyll Docs](https://jekyllrb.com/docs/installation/) to complete the installation of basic environment (`Ruby`, `RubyGems` and `Bundler`).
[Fork **Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/fork) on GitHub, and clone the fork to local by:
To improve the writing experience, we need to use some script tools. If your machine is running Debian or macOS, make sure that [GNU coreutils](https://www.gnu.org/software/coreutils/) is installed. Otherwise, install by:
```terminal
$ git clone git@github.com:<username>/jekyll-theme-chirpy -b master --single-branch
```
### Setting up the local envrionment
If you would like to run or build the project on your local machine, please follow the [Jekyll Docs](https://jekyllrb.com/docs/installation/) to complete the installation of `Ruby`, `RubyGems` and `Bundler`.
Before running or building for the first time, please complete the installation of the Jekyll plugins. Go to the root directory of project and run:
```terminal
$ bundle install
```
`bundle` will automatically install all the dependencies specified by `Gemfile`.
What's more, in order to generate some extra files (*categories*, *tags* and *last modified list*), we need to use some tool scripts. If your machine is running Debian or macOS, make sure that [GNU coreutils](https://www.gnu.org/software/coreutils/) is installed. Otherwise, install by:
* Debian
@ -58,123 +73,76 @@ To improve the writing experience, we need to use some script tools. If your mac
```
### 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 -b master
```
And replace the `USER` above to your GitHub username.
The first time you run or build the project on local machine, perform the installation of Jekyll plugins. Go to the root of repo and run:
```terminal
$ bundle install
```
`bundle` will automatically install all the dependent Jekyll Plugins that listed in the `Gemfile`.
## Usage
Running [**Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/) requires some extra files, which cannot be generated by Jekyll native commands, so please strictly follow the methods mentioned below to run or deploy your website.
### Directory Structure
### Initialization
The main files and related brief introductions are listed below:
Go to the root directory of the project and start initialization:
```sh
jekyll-theme-chirpy/
├── _data
├── _includes
├── _layouts
├── _posts # posts stay here
├── _scripts
├── .travis.yml # remove it
├── .github # remove this, too
├── assets
├── tabs
│   └── about.md # the ABOUT page
├── .gitignore
├── 404.html
├── Gemfile
├── LICENSE
├── README.md
├── _config.yml # configuration file
├── tools # script tools
├── docs
├── feed.xml
├── index.html
├── robots.txt
└── sitemap.xml
```console
$ bash tools/init.sh
```
> If you not intend to deploy it on GitHub Pages, append parameter option `--no-gh` at the end of the above command.
As mentioned above, some files or directories should be removed from your repo:
What it does is:
```terminal
$ rm -rf .travis.yml .github _posts/*
```
1. Remove some files or directories from your repository:
- `.travis.yml`
- everything under `.github/`
- files under `_posts/`
- folder `docs/`
2. Unless the option `--no-gh` was enabled, setup the GitHub action workflow by renaming `pages-deploy.yml.hook` of directory `.github/workflows/` to `pages-deploy.yml`.
3. Automatically create a commit to save the changes.
### Configuration
Generally, go to `_config.yml` and configure the variables as needed. Some of them are typical options:
* `url`
Set to your website url and there should be no slash symbol at the tail. Format: `<protocol>://<domain>`.
* `avatar`
It defines the image file location of avatar. The sample image is `/assets/img/sample/avatar.jpg`, and should be replaced by your own one(a square image). Notice that a huge image file will increase the load time of your site, so keep your avatar image size as small as possible(may be *<https://tinypng.com/>* will help).
* `timezone`
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).
* `theme_mode`
There are three options for the theme color scheme:
- **dual** - The default color scheme will follow the system settings, but if the system does not support dark mode, or the browser does not support `Media Queries Level 5`, the theme will be displayed as `light` mode by default. Anyway, the bottom left corner of the Sidebar will provide a button for users to switch color schemes.
### Run Locally
- **dark** - Always show dark mode.
- **light** - Always show light mode.
### Run Locally
You may want to preview the site content before publishing, so just run the script tool:
You may want to preview the site contents before publishing, so just run it by:
```terminal
$ bash tools/run.sh
```
Open a modern browser and visit at <http://localhost:4000>.
Then open a browser and visit to <http://localhost:4000>.
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.
Few days later, you may find that the file changes 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.
### Deploying to GitHub Pages
### Deployment
Before the deployment begins, checkout the file `_config.yml` and make sure that the `url` has been configured. What's more, if you prefer the [Project site on GitHub](https://help.github.com/en/github/working-with-github-pages/about-github-pages#types-of-github-pages-sites) and also use the default domain `<username>.github.io`, remember to change the `baseurl` to your project name that starting with a slash. For example, `/project`.
Before the deployment begins, checkout the file `_config.yml` and make sure the `url` is configured correctly. Furthermore, if you prefer the [_project site_](https://help.github.com/en/github/working-with-github-pages/about-github-pages#types-of-github-pages-sites) and don't use a custom domain, or you want to visit your website with a base url on a web server other than **GitHub Pages**, remember to change the `baseurl` to your project name that starting with a slash. For example, `/project`.
#### Option 1: Built by GitHub Pages
Assuming you have already gone through the [initialization](#initialization), you can now choose any of the following methods to deploy your website.
By deploying the site in this way, you're allowed to push the source code directly to the remote.
#### Deploy on GitHub Pages
> **Note**: If you want to use any third-party Jekyll plugins that not on [this list](https://pages.github.com/versions/), stop reading the current approach and go to [*Option 2: Build locally*](#option-2-build-locally).
For security reasons, GitHub Pages build runs on `safe` mode, which restricts us from using tool scripts to generate additional page files. Therefore, we can use GitHub Actions to build the site, store the built site files on a new branch, and use that branch as the source of the Pages service.
**1**. Rename the repository to:
1. Push any commit to `origin/master` to trigger the GitHub Actions workflow. Once the build is complete, a new remote branch called `gh-pages` will appear, which is used to store the built site files.
|Site Type | Repo's Name|
|:---|:---|
|User or Organization | `<username>.github.io`|
|Project| Any one except `<username>.github.io`, let's say `project`|
2. Unless you prefer to project sites, rename your repository to `<username>.github.io` on GitHub.
**2**. Commit the changes of the repo first, then run the publish script:
3. Choose branch `gh-pages` as your GitHub Pages source.
4. Visit your website at the address indicated by GitHub.
#### Deploy on Other Platforms
On platforms other than GitHub, e.g. GitLab, we cannot enjoy the convenience of **GitHub Actions**. However, we have a tool to make up for this shortcoming.
Commit the changes of your repository first, then run the publish script:
```console
$ bash tools/publish.sh
@ -182,7 +150,7 @@ $ bash tools/publish.sh
> Please note that the *Recent Update* list requires the latest git-log date of posts, thus make sure the changes in `_posts` have been committed before running this command.
it will automatically generates the *Latest Modified Date* and *Categories / Tags* page for the posts and submit a commit, and then push to `origin/master`. Its output is similar to the following log:
It will automatically generates the *Latest Modified Date* and *Categories / Tags* page for the posts and submit a commit, then push to `origin/master`. Its output is similar to the following log:
```terminal
[INFO] Success to update lastmod for 4 post(s).
@ -191,54 +159,21 @@ it will automatically generates the *Latest Modified Date* and *Categories / Tag
[INFO] Published successfully!
```
**3**. Go to GitHub website and enable GitHub Pages service for the repo.
Lastly, enable the pages service according to the instructions of the platform you choose.
**4**. Check it out:
#### Deploy on Private Server
|Site Type | Site URL |
|:---|:---|
|User or Organization | `https://<username>.github.io/`|
|Project| `https://<username>.github.io/project/`|
#### Option 2: Build Locally
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 other plugin that not on 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`|
and clone it.
**2**. In the root of the source project, build your site by:
In the root of the source project, build your site by:
```console
$ bash tools/build.sh -d /path/to/local/project/
$ bash tools/build.sh -d /path/to/site/
```
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.
**4**. Visit at:
|Site Type | Site URL |
|:---|:---|
|User or Organization | `https://<username>.github.io/`|
|Project| `https://<username>.github.io/project/`|
#### Finishing work
No matter which way you choose to deploy the website on GitHub, please enforce the `HTTPS` for it. See official docs: [Securing your GitHub Pages site with HTTPS](https://help.github.com/en/github/working-with-github-pages/securing-your-github-pages-site-with-https).
The generated site files will be placed in the root of `/path/to/site/`. Now you should upload those files to your web server, such as Nginx.
### 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).
For more details and the better reading experience, please check out the [tutorials on 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
@ -247,14 +182,14 @@ The old saying, "Two heads are better than one." Consequently, welcome to report
## Credits
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).
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).
:tada:Thanks to all the volunteers who contributed to this project, their GitHub IDs are on [this list](https://github.com/cotes2020/jekyll-theme-chirpy/graphs/contributors). Also, I won't forget those guys who submitted the issues or unmerged PR because they reported bugs, shared ideas or inspired me to write more readable documentation.
:tada: Thanks to all the volunteers who contributed to this project, their GitHub IDs are on [this list](https://github.com/cotes2020/jekyll-theme-chirpy/graphs/contributors). Also, I won't forget those guys who submitted the issues or unmerged PR because they reported bugs, shared ideas or inspired me to write more readable documentation.
## Support
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 and help me better maintain the project.
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 and help me better maintain the project.
## License

31
_posts/2019-08-08-write-a-new-post.md
View file

@ -8,7 +8,7 @@ tags: [writing]
## Naming and Path
Create a new file named with the format `YYYY-MM-DD-title.md` then put it into `_post` of the root directory.
Create a new file named `YYYY-MM-DD-TITLE.EXTENSION` and put it in the `_post/` of the root directory. The `EXTENSION` must be one of `md` and `markdown`. From `v2.4.1`, you can create sub-directories under `_posts/` to categorize posts.
## Front Matter
@ -33,27 +33,28 @@ In order to accurately record the release date of a post, you should not only se
The `categories` of each post is designed to contain up to two elements, and the number of elements in `tags` can be zero to infinity.
The list of posts belonging to the same category/tag is recorded on a separate page. The number of such *category*/*tag* type pages is equal to the number of `categories`/`tags` for all posts, they must match perfectly.
The list of posts belonging to the same _category_/_tag_ is recorded on a separate page. At the same time, the number of these _category_/_tag_ type pages is equal to the number of `categories` / `tags` elements for all posts, which means that the two number must be exactly the same.
For instance, let's say there is a post with front matter:
let's say there is a post with front matter:
```yaml
categories: [Animal, Insect]
tags: bee
```
then we should have two *category* type pages placed in folder `categories` of root and one *tag* type page placed in folder `tags` of root:
Then we should have two _category_ type pages placed in folder `categories` of root and one _tag_ type page placed in folder `tags` of root:
```terminal
jekyll-theme-chirpy
```sh
.
├── categories
│   ├── animal.html
│   ├── animal.html # a category type page
│   └── insect.html
├── tags
│   └── bee.html
│   └── bee.html # a tag type page
...
```
and the content of a *category* type page is
and the content of a _category_ type page is
```yaml
---
@ -63,7 +64,7 @@ category: CATEGORY_NAME # e.g. Insect
---
```
the content of a *tag* type page is
the content of a _tag_ type page is
```yaml
---
@ -73,11 +74,11 @@ tag: TAG_NAME # e.g. bee
---
```
With the increasing number of posts, the number of categories and tags will increase several times! If we still manually create these *category*/*tag* type files, it will obviously be a super time-consuming job, and it is very likely to miss some of them(i.e. when you click on the missing `category` or `tag` link from a post or somewhere, it will complain to you '404'). The good news is that we got a lovely script tool `_scripts/sh/create_pages.sh` to finish the boring task. Basically we will use it via `tools/publish.sh` instead of running it separately. Check out its use case [here]({{ "/posts/getting-started/#option-1-built-by-github-pages" | relative_url }}).
With the increasing number of posts, the number of categories and tags will increase several times! If we still manually create these *category*/_tag_ type files, it will obviously be a super time-consuming job, and it is very likely to miss some of them, i.e., when you click on the missing `category` or `tag` link from a post or somewhere, the browser will complain to you "404 Not Found". The good news is we got a lovely script tool `_scripts/sh/create_pages.sh` to finish the boring tasks. Basically we will use it via `run.sh`, `build.sh`, `deploy.sh` or `publish.sh` that placed in `tools/` instead of running it separately. Check out its use case [here]({{ "/posts/getting-started/#deployment" | relative_url }}).
## Last modified date
The last modified date of a post is obtained according to its latest git commit date, and all the modified date of the posts should be stored in `_data/updates.yml`. For example:
The last modified date of a post is obtained according to the post's latest git commit date, and the modified date of all posts are designed to be stored in the file `_data/updates.yml`. Then contents of that file may be as follows:
```yaml
-
@ -87,13 +88,13 @@ The last modified date of a post is obtained according to its latest git commit
...
```
You can choose to create this file manually, but as you may notice, the better approach is to let it be automatically generated by a tool script. And `_scripts/sh/dump_lastmod.sh` was born for this! Similar to the another script `_scripts/sh/create_pages.sh` mentioned above, it is also be called from `tools/publish.sh`, so it doesn't have to be used separately.
You can choose to create this file manually, But the better approach is to let it be automatically generated by a script tool, and `_scripts/sh/dump_lastmod.sh` was born for this! Similar to the other script (`create_pages.sh`) mentioned above, it is also be called from the other superior tools, so it doesn't have to be used separately.
When some posts have been modified since their published date and also the file `_data/updates.yml` was created correctly, a list with the label **Recent Updates** will be displayed in the right panel of the desktop view, which records the five most recently modified articles.
When some posts have been modified since their published date and also the file `_data/updates.yml` was created correctly, a list with the label **Recent Updates** will be displayed in the right panel of the desktop view, which records the five most recently modified posts.
## Table of Contents
By default, the **T**able **o**f **C**ontents (TOC) is displayed on the right panel of the post. If you want to turn it off globally, go to `_config.yml` and set the variable `toc` to `false`. If you want to turn off TOC for specific post, add the following to post's [Front Matter](https://jekyllrb.com/docs/front-matter/):
By default, the **T**able **o**f **C**ontents (TOC) is displayed on the right panel of the post. If you want to turn it off globally, go to `_config.yml` and set the value of variable `toc` to `false`. If you want to turn off TOC for specific post, add the following to post's [Front Matter](https://jekyllrb.com/docs/front-matter/):
```yaml
---

180
_posts/2019-08-09-getting-started.md
View file

@ -7,11 +7,28 @@ tags: [getting started]
pin: true
---
## Prerequisites
Follow the [Jekyll Docs](https://jekyllrb.com/docs/installation/) to complete the installation of basic environment (`Ruby`, `RubyGems` and `Bundler`).
## Installation
To improve the writing experience, we need to use some script tools. If your machine is running Debian or macOS, make sure that [GNU coreutils](https://www.gnu.org/software/coreutils/) is installed. Otherwise, install by:
[Fork **Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/fork) on GitHub, and clone the fork to local by:
```terminal
$ git clone git@github.com:<username>/jekyll-theme-chirpy -b master --single-branch
```
### Setting up the local envrionment
If you would like to run or build the project on your local machine, please follow the [Jekyll Docs](https://jekyllrb.com/docs/installation/) to complete the installation of `Ruby`, `RubyGems` and `Bundler`.
Before running or building for the first time, please complete the installation of the Jekyll plugins. Go to the root directory of project and run:
```terminal
$ bundle install
```
`bundle` will automatically install all the dependencies specified by `Gemfile`.
What's more, in order to generate some extra files (*categories*, *tags* and *last modified list*), we need to use some tool scripts. If your machine is running Debian or macOS, make sure that [GNU coreutils](https://www.gnu.org/software/coreutils/) is installed. Otherwise, install by:
* Debian
@ -26,119 +43,76 @@ To improve the writing experience, we need to use some script tools. If your mac
```
## Jekyll Plugins
## Usage
[Fork **Chirpy** from GitHub](https://github.com/cotes2020/jekyll-theme-chirpy/fork), then clone your forked repo to local:
Running [**Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/) requires some extra files, which cannot be generated by Jekyll native commands, so please strictly follow the methods mentioned below to run or deploy your website.
### Initialization
Go to the root directory of the project and start initialization:
```console
$ git clone git@github.com:USER/jekyll-theme-chirpy.git -b master
$ bash tools/init.sh
```
And replace the `USER` above to your GitHub username.
> If you not intend to deploy it on GitHub Pages, append parameter option `--no-gh` at the end of the above command.
The first time you run or build the project on local machine, perform the installation of Jekyll plugins. Go to the root of repo and run:
What it does is:
```terminal
$ bundle install
```
1. Remove some files or directories from your repository:
- `.travis.yml`
- everything under `.github/`
- files under `_posts/`
- folder `docs/`
`bundle` will automatically install all the dependent Jekyll Plugins that listed in the `Gemfile`.
2. Unless the option `--no-gh` was enabled, setup the GitHub action workflow by renaming `pages-deploy.yml.hook` of directory `.github/workflows/` to `pages-deploy.yml`.
3. Automatically create a commit to save the changes.
## Directory Structure
The main files and related brief introductions are listed below:
```sh
jekyll-theme-chirpy/
├── _data
├── _includes
├── _layouts
├── _posts # posts stay here
├── _scripts
├── .travis.yml # remove it
├── .github # remove this, too
├── assets
├── tabs
│   └── about.md # the ABOUT page
├── .gitignore
├── 404.html
├── Gemfile
├── LICENSE
├── README.md
├── _config.yml # configuration file
├── tools # script tools
├── feed.xml
├── index.html
├── robots.txt
└── sitemap.xml
```
As mentioned above, some files or directories should be removed from your repo:
```terminal
$ rm -rf .travis.yml .github _posts/*
```
## Configuration
### Configuration
Generally, go to `_config.yml` and configure the variables as needed. Some of them are typical options:
* `url`
Set to your website url and there should be no slash symbol at the tail. Format: `<protocol>://<domain>`.
* `avatar`
It defines the image file location of avatar. The sample image is `/assets/img/sample/avatar.jpg`, and should be replaced by your own one (a square image). Notice that a huge image file will increase the load time of your site, so keep your avatar image size as small as possible (may be *<https://tinypng.com/>* will help).
* `timezone`
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).
* `theme_mode`
There are three options for the theme color scheme:
- **dual** - The default color scheme will follow the system settings, but if the system does not support dark mode, or the browser does not support `Media Queries Level 5`, the theme will be displayed as `light` mode by default. Anyway, the bottom left corner of the Sidebar will provide a button for users to switch color schemes.
### Run Locally
- **dark** - Always show dark mode.
- **light** - Always show light mode.
## Run Locally
You may want to preview the site content before publishing, so just run the script tool:
You may want to preview the site contents before publishing, so just run it by:
```terminal
$ bash tools/run.sh
```
Open a browser and visit <http://localhost:4000>.
Then open a browser and visit to <http://localhost:4000>.
Few days later, you may find that the file changes 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.
## Deploying to GitHub Pages
### Deployment
Before the deployment begins, checkout the file `_config.yml` and make sure that the `url` has been configured. What's more, if you prefer the [Project site on GitHub](https://help.github.com/en/github/working-with-github-pages/about-github-pages#types-of-github-pages-sites) and also use the default domain `<username>.github.io`, remember to change the `baseurl` to your project name that starting with a slash. For example, `/project`.
Before the deployment begins, checkout the file `_config.yml` and make sure the `url` is configured correctly. Furthermore, if you prefer the [_project site_](https://help.github.com/en/github/working-with-github-pages/about-github-pages#types-of-github-pages-sites) and don't use a custom domain, or you want to visit your website with a base url on a web server other than **GitHub Pages**, remember to change the `baseurl` to your project name that starting with a slash. For example, `/project`.
Assuming you have already gone through the [initialization](#initialization), you can now choose any of the following methods to deploy your website.
### Option 1: Built by GitHub Pages
#### Deploy on GitHub Pages
By deploying the site in this way, you're allowed to push the source code directly to the remote.
For security reasons, GitHub Pages build runs on `safe` mode, which restricts us from using tool scripts to generate additional page files. Therefore, we can use GitHub Actions to build the site, store the built site files on a new branch, and use that branch as the source of the Pages service.
> **Note**: If you want to use any third-party Jekyll plugins that not on [this list](https://pages.github.com/versions/), stop reading the current approach and go to [*Option 2: Build locally*](#option-2-build-locally).
1. Push any commit to `origin/master` to trigger the GitHub Actions workflow. Once the build is complete, a new remote branch called `gh-pages` will appear, which is used to store the built site files.
**1**. Rename the repository to:
2. Unless you prefer to project sites, rename your repository to `<username>.github.io` on GitHub.
|Site Type | Repo's Name|
|:---|:---|
|User or Organization | `<username>.github.io`|
|Project| Any one except `<username>.github.io`, let's say `project`|
3. Choose branch `gh-pages` as your GitHub Pages source.
**2**. Commit the changes of the repo first, then run the publish script:
4. Visit your website at the address indicated by GitHub.
#### Deploy on Other Platforms
On platforms other than GitHub, e.g. GitLab, we cannot enjoy the convenience of **GitHub Actions**. However, we have a tool to make up for this shortcoming.
Commit the changes of your repository first, then run the publish script:
```console
$ bash tools/publish.sh
@ -146,7 +120,7 @@ $ bash tools/publish.sh
> Please note that the *Recent Update* list requires the latest git-log date of posts, thus make sure the changes in `_posts` have been committed before running this command.
it will automatically generates the *Latest Modified Date* and *Categories / Tags* page for the posts and submit a commit, and then push to `origin/master`. Its output is similar to the following log:
It will automatically generates the *Latest Modified Date* and *Categories / Tags* page for the posts and submit a commit, then push to `origin/master`. Its output is similar to the following log:
```terminal
[INFO] Success to update lastmod for 4 post(s).
@ -155,46 +129,14 @@ it will automatically generates the *Latest Modified Date* and *Categories / Tag
[INFO] Published successfully!
```
**3**. Go to GitHub website and enable GitHub Pages service for the repo.
Lastly, enable the pages service according to the instructions of the platform you choose.
**4**. Check it out:
#### Deploy on Private Server
|Site Type | Site URL |
|:---|:---|
|User or Organization | `https://<username>.github.io/`|
|Project| `https://<username>.github.io/project/`|
### Option 2: Build Locally
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 other plugin that not on 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`|
and clone it.
**2**. In the root of the source project, build your site by:
In the root of the source project, build your site by:
```console
$ bash tools/build.sh -d /path/to/local/project/
$ bash tools/build.sh -d /path/to/site/
```
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.
**4**. Visit at:
|Site Type | Site URL |
|:---|:---|
|User or Organization | `https://<username>.github.io/`|
|Project| `https://<username>.github.io/project/`|
### Finishing work
No matter which way you choose to deploy the website on GitHub, please enforce the `HTTPS` for it. See official docs: [Securing your GitHub Pages site with HTTPS](https://help.github.com/en/github/working-with-github-pages/securing-your-github-pages-site-with-https).
The generated site files will be placed in the root of `/path/to/site/`. Now you should upload those files to your web server, such as Nginx.

195
docs/README_zh-CN.md
View file

@ -14,15 +14,15 @@
## 目录
* [功能预览](#功能预览)
* [功能一览](#功能一览)
* [安装](#安装)
* [运行指南](#运行指南)
* [使用](#使用)
* [参与贡献](#参与贡献)
* [感谢](#感谢)
* [赞助](#赞助)
* [许可证书](#许可证书)
## 功能预览
## 功能一览
* 文章置顶
* 可配置的全局主题颜色
@ -43,110 +43,76 @@
## 安装
### 准备工作
[Fork **Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/fork)，然后克隆到本地：
按照 [Jekyll 官方文档](https://jekyllrb.com/docs/installation/) 完成基础环境的安装 (`Ruby`，`RubyGem`，`Bundler`)。
为了使用项目内免费提供的脚本工具增进写作体验，如果你的机器系统是 Debian 或者 macOS，则需要确保安装了 [GNU coreutils](https://www.gnu.org/software/coreutils/)。否则，通过以下方式获得：
* Debian
```console
$ sudo apt-get install coreutils
```
* macOS
```console
$ brew install coreutils
```
接着，[fork](https://github.com/cotes2020/jekyll-theme-chirpy/fork) 一份代码，然后克隆你 Fork 的仓库到本地机器上。
```console
$ git clone git@github.com:USER/jekyll-theme-chirpy.git -b master
```terminal
$ git clone git@github.com:<username>/jekyll-theme-chirpy -b master --single-branch
```
把上述的`USER` 替换为你的 GitHub username。
### 设置本地环境
如果你想在本地运行或构建, 参考 [Jekyll Docs](https://jekyllrb.com/docs/installation/)安装 `Ruby`， `RubyGems` 和 `Bundler`。
### 安装 Jekyll 插件
本地首次运行或编译，请在项目根目录下运行:
首次运行或构建时, 请先安装 Jekyll plugins。在项目根目录运行：
```terminal
$ bundle install
```
`bundle` 命令会自动安装 `Gemfile` 内声明的依赖插件.
`bundle` 会自动安装 `Gemfile` 内指定的依赖插件。
另外，为了生成一些额外的文件（ Post 的分类、标签以及更新时间列表），需要用到一些脚本工具。如果你电脑的操作系统是 Debian 或者 macOS，请确保已经安装了[GNU coreutils](https://www.gnu.org/software/coreutils/)，否则，通过以下方式完成安装：
* Debian
```console
$ sudo apt-get install coreutils
```
* macOS
```console
$ brew install coreutils
```
## 使用
## 运行指南
运行 [**Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/) 需要一些额外的文件, 它们不能通过 Jekyll 原生的命令生成，所以请严格依照下列说明去运行或部署此项目。
### 文件目录
### 初始化
下面是主要的文件目录：
在项目根目录，开始初始化:
```sh
jekyll-theme-chirpy/
├── _data
├── _includes
├── _layouts
├── _posts # posts stay here
├── _scripts
├── .travis.yml # remove it
├── .github # remove this, too
├── assets
├── tabs
│   └── about.md # the ABOUT page
├── .gitignore
├── 404.html
├── Gemfile
├── LICENSE
├── README.md
├── _config.yml # configuration file
├── tools # script tools
├── docs
├── feed.xml
├── index.html
├── robots.txt
└── sitemap.xml
```console
$ bash tools/init.sh
```
> 如果你不打算部署到 GitHub Pages, 在上述命令后附加参数选项 `--no-gh`。
如备注所述，部分文件或目录需要被删除:
上述脚本完成了以下工作:
```terminal
$ rm -rf .travis.yml .github _posts/*
```
1. 从你的仓库中删除了:
- `.travis.yml`
- `.github` 下的文件和目录
- `_posts` 下的文件
- `docs` 目录
2. 配置了 GitHub Actions：把 `.github/workflows/` 的文件 `pages-deploy.yml.hook` 重命名为 `pages-deploy.yml`。
3. 自动提交一个 Commit 以保存文件的更改。
### 配置文件
根据个人需要去修改 `_config.yml` 的变量，大部分都有注释介绍用法。
根据个人需要去修改 `_config.yml` 的变量，大部分都有注释介绍用法。典型的几个选项是：
* `url`
定义网站 URL，注意结尾不带 `/`。格式： `<protocol>://<domain>`.
* `avatar`
定义头像，示例的文件放置在：`/assets/img/sample/avatar.jpg`. 把它换成你自己的头像，路径不限定，越小越好。(压缩图像体积可上这个网站：*<https://tinypng.com/>* ).
* `timezone`
定义时区 ，默认为 `亚洲/上海`，如果肉身翻墙要换城市可在此列表找到： [TimezoneConverter](http://www.timezoneconverter.com/cgi-bin/findzone/findzone) 或者 [Wikipedia](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
* `theme_mode`
定义颜色方案，有三种可选：:
- **dual** - 自动跟随系统的 `深色`/`浅色` 设置，当系统或者浏览器不支持深色模式，则默认显示为浅色模式。无论如何，侧边栏左下角都会显示一个颜色切换按钮。
- **dark** - 全程深色模式。
- **light** - 全程浅色模式。
### 本地运行
### 本地运行
使用以下工具可轻松运行:
@ -158,24 +124,30 @@ $ bash tools/run.sh
如果你想在本地服务运行后，把修改源文件的更改实时刷新，可使用选项 `-r` (或 `--realtime`)，不过要先安装依赖 [**fswatch**](http://emcrisostomo.github.io/fswatch/) 。
### 部署到 GitHub Pages
### 部署
部署开始前，把 `_config.yml` 的 `url` 改为 `https://<username>.github.io`(或者你的私有域名，如：`https://yourdomain.com`)。另外，如果你想使用 [Project 类型网站](https://help.github.com/en/github/working-with-github-pages/about-github-pages#types-of-github-pages-sites)，修改配置文件的 `baseurl` 为项目名称，以斜杠开头，如：`/project`。
#### 方法 1: 由 GitHub Pages 生成站点
假设你已经完成了 [初始化](#初始化)，现在你可以选择下列其中一个方式去站点部署。
依照本方法，你可以直接把源码推送到远端仓库。
#### 部署到 GitHub Pages
> **注**: 如果你想使用任何不在这个[列表](https://pages.github.com/versions/)上的插件，越过此方法，直接看 [*方法 2: 本地构建*](#方法-2-本地构建).
由于安全原因，GitHub Pages 的构建强制加了 `safe`参数，这导致了我们不能使用脚本工具去创建所需的附加页面。因此，我们可以使用 GitHub Actions 去构建站点，把站点文件存储在一个新分支上，再指定该分支作为 Pages 服务的源。
**1**. 仓库改名为:
1. 推送任意一个 commit 到 `origin/master` 以触发 GitHub Actions workflow。一旦 build 完毕，远端将会自动出现一个新分支 `gh-pages` 用来存储构建的站点文件。
|站点类型 | 仓库名称|
|:---|:---|
|User or Organization | `<username>.github.io`|
|Project| `<username>.github.io` 以外的名字，譬如 `project`|
2. 除非你是使用 project 站点, 否则重命名你的仓库为 `<username>.github.io`。
**2**. 提交本地更改，然后运行:
3. 选择分支 `gh-pages` 作为 GitHub Pages 的源.
4. 按照 GitHub 指示的地址去访问你的网站。
#### 部署到其他 Pages 平台
在 GitHub 之外的平台，例如 GitLab，就没法享受 **GitHub Actions** 的便利了。不过先别慌，可以通过工具来弥补这个遗憾。
先把本地仓库的 upstream 改为新平台的仓库地址，推送一发。以后每次更新内容后，提交 commit ，然后运行:
```console
$ bash tools/publish.sh
@ -192,50 +164,17 @@ $ bash tools/publish.sh
[INFO] Published successfully!
```
**3**. 到 GitHub 网页为该项目开启 Pages 服务。
最后，根据平台的说明文档为项目开启 Pages 服务。
**4**. 网站将运行在：
#### 部署到私人服务器
|站点类型 | 网站 URL |
|:---|:---|
|User or Organization | `https://<username>.github.io/`|
|Project| `https://<username>.github.io/project/`|
#### 方法 2: 本地构建
由于安全原因，GitHub Pages 不允许第三方插件运行，如果你想突破规则，就要本地构建站点内容。
**1**. 到 GitHub 网页，创建一个新的仓库，根据以下规则命名:
|站点类型 | 仓库名称|
|:---|:---|
|User or Organization | `<username>.github.io`|
|Project| `<username>.github.io` 以外的名字， 例如 `project`|
然后 Clone 新仓库到本地。
**2**. 构建站点:
在项目更目录，运行:
```console
$ bash tools/build.sh -d /path/to/local/project/
$ bash tools/build.sh -d /path/to/site/
```
> `project` 为新仓库名称。
生成的静态文件将会在 `/path/to/local/project`. 把新仓库的修改提交并推送到远端 `master` 分支.
**3**. 回到 GithHub 网页，为该仓库开启 Pages 服务。
**4**. 网站将运行在:
|站点类型 | 站点 URL |
|:---|:---|
|User or Organization | `https://<username>.github.io/`|
|Project| `https://<username>.github.io/project/`|
#### 结束工作
无论你选择了哪种方式部署网站到 GitHub Pages, 请开启 `HTTPS` 功能。具体细节参考官方说明：[Securing your GitHub Pages site with HTTPS](https://help.github.com/en/github/working-with-github-pages/securing-your-github-pages-site-with-https)。
生成的静态文件将会在 `/path/to/site/`， 把内部的文件上传到服务器即可。
### 文档
@ -250,12 +189,12 @@ $ bash tools/build.sh -d /path/to/local/project/
这个主题的开发主要基于 [Jekyll](https://jekyllrb.com/) 生态、[Bootstrap](https://getbootstrap.com/)、[Font Awesome](https://fontawesome.com/) 和其他一些出色的工具 (相关文件中可以找到这些工具的版权信息).
:tada:感谢所有参与代码贡献的小伙伴, 他们的 GayHub ID 在这个[列表](https://github.com/cotes2020/jekyll-theme-chirpy/graphs/contributors)。 另外, 提交过 issues(或者未被合并 PR) 的高富帅和白富美也不会被遗忘,他/她们帮助报告 bug、分享新点子或者启发了我写出更通俗易懂的文档。
:tada: 感谢所有参与代码贡献的小伙伴, 他们的 GayHub ID 在这个[列表](https://github.com/cotes2020/jekyll-theme-chirpy/graphs/contributors)。 另外, 提交过 issues(或者未被合并 PR) 的高富帅和白富美也不会被遗忘,他/她们帮助报告 bug、分享新点子或者启发了我写出更通俗易懂的文档。
## 赞助
如果您喜欢这个主题或者它对您有帮助，请考虑打赏作者：在 [项目主页](https://github.com/cotes2020/jekyll-theme-chirpy) 点击按钮 <kbd>:heart:Sponsor</kbd> 选择适合的链接即可完成（国内一般选第二个链接，支付宝/微信赞助），您的打赏将会极大地鼓励作者，并帮助作者更好地维护项目！
如果您喜欢这个主题或者它对您有帮助，请考虑打赏作者：在 [项目主页](https://github.com/cotes2020/jekyll-theme-chirpy) 点击按钮 <kbd>:heart: Sponsor</kbd> 选择适合的链接即可完成（国内一般选第二个链接，支付宝/微信赞助），您的打赏将会极大地鼓励作者，并帮助作者更好地维护项目！
## 许可证书