From adff74b27b79d9802d0803d413960459f1b80256 Mon Sep 17 00:00:00 2001 From: Cotes Chung <11371340+cotes2020@users.noreply.github.com> Date: Mon, 3 Aug 2020 02:25:40 +0800 Subject: [PATCH] Update docs for v2.5 --- README.md | 195 +++++++++----------------- _posts/2019-08-08-write-a-new-post.md | 33 ++--- _posts/2019-08-09-getting-started.md | 180 ++++++++---------------- docs/README_zh-CN.md | 195 +++++++++----------------- 4 files changed, 210 insertions(+), 393 deletions(-) diff --git a/README.md b/README.md index aef6ef0..52a2f90 100644 --- a/README.md +++ b/README.md @@ -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:/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: `://`. - - * `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 ** 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. - - - **dark** - Always show dark mode. - - **light** - Always show light mode. -### Run Locally +### 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 . +Then open a browser and visit to . -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 `.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 | `.github.io`| -|Project| Any one except `.github.io`, let's say `project`| +2. Unless you prefer to project sites, rename your repository to `.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://.github.io/`| -|Project| `https://.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 | `.github.io`| -|Project| Any one except `.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://.github.io/`| -|Project| `https://.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 :heart:Sponsor 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 :heart: Sponsor 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 diff --git a/_posts/2019-08-08-write-a-new-post.md b/_posts/2019-08-08-write-a-new-post.md index 3e7929d..4102687 100644 --- a/_posts/2019-08-08-write-a-new-post.md +++ b/_posts/2019-08-08-write-a-new-post.md @@ -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 --- diff --git a/_posts/2019-08-09-getting-started.md b/_posts/2019-08-09-getting-started.md index fbd4682..62bfb8b 100644 --- a/_posts/2019-08-09-getting-started.md +++ b/_posts/2019-08-09-getting-started.md @@ -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:/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: `://`. - - * `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 ** 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. - - - **dark** - Always show dark mode. - - **light** - Always show light mode. -## Run Locally +### 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 . +Then open a browser and visit to . 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 `.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 `.github.io` on GitHub. -|Site Type | Repo's Name| -|:---|:---| -|User or Organization | `.github.io`| -|Project| Any one except `.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://.github.io/`| -|Project| `https://.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 | `.github.io`| -|Project| Any one except `.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://.github.io/`| -|Project| `https://.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. diff --git a/docs/README_zh-CN.md b/docs/README_zh-CN.md index d0b6ef9..d5513ec 100644 --- a/docs/README_zh-CN.md +++ b/docs/README_zh-CN.md @@ -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:/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，注意结尾不带 `/`。格式： `://`. - * `avatar` - - 定义头像，示例的文件放置在：`/assets/img/sample/avatar.jpg`. 把它换成你自己的头像，路径不限定，越小越好。(压缩图像体积可上这个网站：** ). - * `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://.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 | `.github.io`| -|Project| `.github.io` 以外的名字，譬如 `project`| +2. 除非你是使用 project 站点, 否则重命名你的仓库为 `.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://.github.io/`| -|Project| `https://.github.io/project/`| - - -#### 方法 2: 本地构建 - -由于安全原因，GitHub Pages 不允许第三方插件运行，如果你想突破规则，就要本地构建站点内容。 - -**1**. 到 GitHub 网页，创建一个新的仓库，根据以下规则命名: - -|站点类型 | 仓库名称| -|:---|:---| -|User or Organization | `.github.io`| -|Project| `.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://.github.io/`| -|Project| `https://.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) 点击按钮 :heart:Sponsor 选择适合的链接即可完成（国内一般选第二个链接，支付宝/微信赞助），您的打赏将会极大地鼓励作者，并帮助作者更好地维护项目！ +如果您喜欢这个主题或者它对您有帮助，请考虑打赏作者：在 [项目主页](https://github.com/cotes2020/jekyll-theme-chirpy) 点击按钮 :heart: Sponsor 选择适合的链接即可完成（国内一般选第二个链接，支付宝/微信赞助），您的打赏将会极大地鼓励作者，并帮助作者更好地维护项目！ ## 许可证书