Merge branch 'feature/docs' into develop

.github/ISSUE_TEMPLATE/bug_report.md

@@ -36,6 +36,7 @@ Steps to reproduce the behavior:
 - Gem version: <!-- by running: `gem -v`-->
 - Bundler version: <!-- by running: `bundle -v`-->
 - Jekyll version: <!-- by running: `bundle list | grep " jekyll "` -->
+- Theme version: <!-- by running: `gem list | grep jekyll-theme-chirpy` -->
 
 ### Desktop
 <!-- If necessary, uncomment and fill in the following list:

.github/PULL_REQUEST_TEMPLATE.md

@@ -2,9 +2,9 @@
 
 <!-- 
 Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context. List any dependencies that are required for this change.
--->
 
 e.g. Fixes #(issue)
+-->
 
 ## Type of change
 
@@ -22,7 +22,7 @@ Please select the desired item checkbox and change it to "[x]", then delete opti
 Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list any relevant details for your test configuration
 -->
 
-- [ ] I have run `bash ./tools/test.sh --build` (at the root of the project) locally and passed
+- [ ] I have run `bash ./tools/deploy.sh --dry-run` (at the root of the project) locally and passed
 - [ ] I have tested this feature in the browser
 
 ### Test Configuration

README.md

@@ -1,38 +1,27 @@
 <div align="right">
-  <a href="https://github.com/cotes2020/jekyll-theme-chirpy#readme">EN</a> |
-  <a href="https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/docs/README.zh-CN.md">中文 (简体)</a>
+
+  EN /
+  [中文(简体)](https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/docs/README.zh-CN.md)
+
 </div>
 
 <div align="center">
-  <h1>Chirpy Jekyll Theme</h1>
-  <p>
-    <a href="https://rubygems.org/gems/jekyll-theme-chirpy">
-    <img alt="Gem Version" src="https://img.shields.io/gem/v/jekyll-theme-chirpy?color=brightgreen"></img>
-  </a>
-    <a href="https://github.com/cotes2020/jekyll-theme-chirpy/actions?query=branch%3Amaster+event%3Apush">
-    <img alt="Build Status" src="https://github.com/cotes2020/jekyll-theme-chirpy/workflows/build/badge.svg?branch=master&event=push"></img>
-  </a>
-    <a href="https://app.codacy.com/manual/cotes2020/jekyll-theme-chirpy?utm_source=github.com&utm_medium=referral&utm_content=cotes2020/jekyll-theme-chirpy&utm_campaign=Badge_Grade_Dashboard">
-    <img alt="Codacy Badge" src="https://api.codacy.com/project/badge/Grade/8220b926db514f13afc3f02b7f884f4b"></img>
-  </a>
-    <a href="https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/LICENSE">
-    <img alt="GitHub license" src="https://img.shields.io/github/license/cotes2020/jekyll-theme-chirpy.svg"></img>
-  </a>
-    <a href="https://996.icu">
-    <img alt="996.icu" src="https://img.shields.io/badge/link-996.icu-%23FF4D5B.svg"></img>
-  </a>
-  </p>
-</div>
 
-A minimal, sidebar, responsive web design Jekyll theme that focuses on text presentation. Designed to help you easily record and share your knowledge.
+  # Chirpy Jekyll Theme
 
-[Live Demo »](https://chirpy.cotes.info)
+  [![Gem Version](https://img.shields.io/gem/v/jekyll-theme-chirpy?color=brightgreen)](https://rubygems.org/gems/jekyll-theme-chirpy)
+  [![Build Status](https://github.com/cotes2020/jekyll-theme-chirpy/workflows/build/badge.svg?branch=master&event=push)](https://github.com/cotes2020/jekyll-theme-chirpy/actions?query=branch%3Amaster+event%3Apush)
+  [![Codacy Badge](https://api.codacy.com/project/badge/Grade/8220b926db514f13afc3f02b7f884f4b)](https://app.codacy.com/manual/cotes2020/jekyll-theme-chirpy?utm_source=github.com&utm_medium=referral&utm_content=cotes2020/jekyll-theme-chirpy&utm_campaign=Badge_Grade_Dashboard)
+  [![GitHub license](https://img.shields.io/github/license/cotes2020/jekyll-theme-chirpy.svg)](https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/LICENSE)
+  [![996.icu](https://img.shields.io/badge/link-996.icu-%23FF4D5B.svg)](https://996.icu)
 
-<p align="center">
-  <a href="https://chirpy.cotes.info">
-    <img alt="Devices Mockup" src="https://cdn.jsdelivr.net/gh/cotes2020/chirpy-images/commons/devices-mockup.png"></img>
-  </a>
-</p>
+  A minimal, responsive, and powerful Jekyll theme for presenting professional writing.
+
+  **[Live Demo →](https://chirpy.cotes.info)**
+
+  [![Devices Mockup](https://cdn.jsdelivr.net/gh/cotes2020/chirpy-images/commons/devices-mockup.png)](https://chirpy.cotes.info)
+
+</div>
 
 ## Features
 
@@ -55,78 +44,55 @@ A minimal, sidebar, responsive web design Jekyll theme that focuses on text pres
 
 ## Prerequisites
 
-Follow the [Jekyll Docs](https://jekyllrb.com/docs/installation/) to complete the installation of `Ruby`, `RubyGems`, `Jekyll` and `Bundler`. Please note that the version of `Ruby` must meet the requirements of the theme on [RubyGems.org](https://rubygems.org/gems/jekyll-theme-chirpy).
+Follow the instructions in the [Jekyll Docs](https://jekyllrb.com/docs/installation/) to complete the installation of `Ruby`, `RubyGems`, `Jekyll` and `Bundler`.
 
 ## Installation
 
-There are two ways to get the theme:
+### Creating a New Site
 
-- **[Install from RubyGems](#install-from-rubygems)** - Easy to update, isolate irrelevant project files so you can focus on writing.
-- **[Fork on GitHub](#fork-on-github)** - Convenient for custom development, but difficult to update, only suitable for web developers.
+There are two ways to create a new repository for this theme:
 
-### Install from RubyGems
+- **[Using the Chirpy Starter](#option-1-using-the-chirpy-starter)** - Easy to upgrade, isolates irrelevant project files so you can focus on writing.
 
-Add this line to your Jekyll site's `Gemfile`:
+- **[Forking on GitHub](#option-2-forking-on-github)** - Convenient for custom development, but difficult to upgrade. Unless you are familiar with Jekyll and are determined to tweak or contribute to this project, this approach is not recommended.
 
-```ruby
-gem "jekyll-theme-chirpy"
-```
+#### Option 1. Using the Chirpy Starter
 
-And add this line to your Jekyll site's `_config.yml`:
+Create a new repository from the [**Chirpy Starter**][use-starter] and name it `<GH_USERNAME>.github.io`, where `GH_USERNAME` represents your GitHub username.
 
-```yaml
-theme: jekyll-theme-chirpy
-```
+#### Option 2. Forking on GitHub
+
+[Fork **Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/fork) on GitHub and rename it to `<GH_USERNAME>.github.io`. Please note that the default branch code is in development.  If you want the site to be stable, please switch to the [latest tag](https://github.com/cotes2020/jekyll-theme-chirpy/tags) and start writing.
 
 And then execute:
 
 ```console
-$ bundle
+$ bash tools/init.sh
 ```
 
-Next, go to the installed local theme path:
+> **Note**: If you don't want to deploy your site on GitHub Pages, append option `--no-gh` at the end of the above command.
 
-```console
-$ cd "$(bundle info --path jekyll-theme-chirpy)"
-```
+The above command will:
 
-And then copy the critical files (for details, see [starter project][starter]) from the theme's gem to your Jekyll site.
+1. Removes some files or directories from your repository:
+    - `.travis.yml`
+    - files under `_posts`
+    - folder `docs`
 
-> ⚠️ **Watch out for duplicate files!**
->
-> If your Jekyll site is created by the `jekyll new` command, there will be `index.markdown` and `about.markdown` in the root directory of your site. Please be sure to remove them, otherwise they will overwrite the `index.html` and `_tabs/about.html` from this project, resulting in blank or messy pages.
+2. If the option `--no-gh` is provided, the directory `.github` will be deleted. Otherwise, setup the GitHub Action workflow by removing the extension `.hook` of `.github/workflows/pages-deploy.yml.hook`, and then remove the other files and directories in the folder `.github`.
 
-As an alternative, which we recommend, you can create a Jekyll site [**using the starter template**][use-starter] to save time copying files from the theme's gem. We've prepared everything you need there!
+3. Removes item `Gemfile.lock` from `.gitignore`.
 
-### Fork on GitHub
+4. Creates a new commit to save the changes automatically.
 
-[Fork **Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/fork) on GitHub and then clone your fork to local. (Please note that the default branch code is in development.  If you want the blog to be stable, please switch to the [latest tag](https://github.com/cotes2020/jekyll-theme-chirpy/tags) and start writing.)
+### Installing Dependencies
 
-Install gem dependencies by:
+Before running for the first time, go the root directory of your site, and install dependencies as follows:
 
 ```console
 $ bundle
 ```
 
-And then execute:
-
-```console
-$ bash tools/init.sh
-```
-
-> **Note**: If you don't plan to deploy your site on GitHub Pages, append parameter option `--no-gh` at the end of the above command.
-
-What it does is:
-
-1. Remove some files or directories from your repository:
-    - `.travis.yml`
-    - files under `_posts`
-    - folder `docs`
-
-2. If you use the `--no-gh` option, the directory `.github` will be deleted. Otherwise, setup the GitHub Action workflow by removing the extension `.hook` of `.github/workflows/pages-deploy.yml.hook`, and then remove the other files and directories in the folder `.github`.
-
-3. Automatically create a commit to save the changes.
-
 ## Usage
 
 ### Configuration
@@ -142,7 +108,7 @@ Update the variables of `_config.yml` as needed. Some of them are typical option
 
 If you need to customize stylesheet, copy the theme's `assets/css/style.scss` to the same path on your Jekyll site, and then add the custom style at the end of the style file.
 
-Starting from `v4.1.0`, if you want to overwrite the SASS variables defined in `_sass/addon/variables.scss`, create a new file `_sass/variables-hook.scss` and assign new values to the target variable in it.
+Starting from [`v4.1.0`][chirpy-4.1.0], if you want to overwrite the SASS variables defined in `_sass/addon/variables.scss`, create a new file `_sass/variables-hook.scss` and assign new values to the target variable in it.
 
 ### Running Local Server
 
@@ -154,63 +120,91 @@ $ bundle exec jekyll s
 
 Or run the site on Docker with the following command:
 
-```terminal
+```console
 $ docker run -it --rm \
     --volume="$PWD:/srv/jekyll" \
     -p 4000:4000 jekyll/jekyll \
     jekyll serve
 ```
 
-Open a browser and visit to _<http://localhost:4000>_.
+After a while, the local service will be published at _<http://127.0.0.1:4000>_.
 
 ### Deployment
 
 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, e.g, `/project-name`.
 
 Now you can choose ONE of the following methods to deploy your Jekyll site.
 
-#### Deploy on GitHub Pages
+#### Deploy by Using Github Actions
 
-For security reasons, GitHub Pages build runs on `safe` mode, which restricts us from using plugins 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 GH Pages service.
+For security reasons, GitHub Pages build runs on `safe` mode, which restricts us from using plugins 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 GitHub Pages service.
 
 Quickly check the files needed for GitHub Actions build:
 
-- Ensure your Jekyll site has the file `.github/workflows/pages-deploy.yml`. Otherwise, create a new one and fill in the contents of the [workflow file][workflow], and the value of the `on.push.branches` should be the same as your repo's default branch name.
-- Ensure your Jekyll site has file `tools/test.sh` and `tools/deploy.sh`. Otherwise, copy them from this repo to your Jekyll site.
+- Ensure your Jekyll site has the file `.github/workflows/pages-deploy.yml`. Otherwise, create a new one and fill in the contents of the [sample file][workflow], and the value of the `on.push.branches` should be the same as your repo's default branch name.
+
+- Ensure your Jekyll site has file `tools/deploy.sh`. Otherwise, copy it from here to your Jekyll site.
 
-And then rename your repository to `<GH-USERNAME>.github.io` on GitHub.
+- Furthermore, if you have committed `Gemfile.lock` to the repo, and your runtime system is not Linux, don't forget to update the platform list in the lockfile:
+
+  ```console
+  $ bundle lock --add-platform x86_64-linux
+  ```
+
+After the above steps, rename your repository to `<GH_USERNAME>.github.io` on GitHub.
 
 Now publish your Jekyll site by:
 
 1. Push any commit to remote to trigger the GitHub Actions workflow. Once the build is complete and successful, a new remote branch named `gh-pages` will appear to store the built site files.
 
-2. Browse to your repo's landing page on GitHub and select the branch `gh-pages` as the [publishing source](https://docs.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site) through _Settings_ → _Options_ → _GitHub Pages_:
+2. Browse to your repository on GitHub. Select the tab _Settings_, then click _Pages_ in the left navigation bar, and then in the section **Source** of _GitHub Pages_, select the `/(root)` directory of branch `gh-pages` as the [publishing source][pages-src]. Remember to click <kbd>Save</kbd> before leaving.
 
     ![gh-pages-sources](https://cdn.jsdelivr.net/gh/cotes2020/chirpy-images/posts/20190809/gh-pages-sources.png)
 
 3. Visit your website at the address indicated by GitHub.
 
-#### Deploy on Other Platforms
+#### Manually Build and Deploy
 
-On platforms other than GitHub, we cannot enjoy the convenience of **GitHub Actions**. Therefore, we should build the site locally (or on some other 3rd-party CI platform) and then put the site files on the server.
+On self-hosted servers, you cannot enjoy the convenience of **GitHub Actions**. Therefore, you should build the site on your local machine and then upload the site files to the server.
 
-Go to the root of the source project, build your site by:
+Go to the root of the source project, and build your site as follows:
 
 ```console
 $ JEKYLL_ENV=production bundle exec jekyll b
 ```
 
-Or build the site with Docker by:
+Or build the site on Docker:
 
-```terminal
+```console
 $ docker run -it --rm \
     --env JEKYLL_ENV=production \
     --volume="$PWD:/srv/jekyll" \
     jekyll/jekyll \
     jekyll build
 ```
 
-Unless you specified the output path, the generated site files will be placed in folder `_site` of the project's root directory. Now you should upload those files to your web server.
+Unless you specified the output path, the generated site files will be placed in folder `_site` of the project's root directory. Now you should upload those files to the target server.
+
+### Upgrading
+
+It depends on how you use the theme:
+
+- If you are using the theme gem (there will be `gem "jekyll-theme-chirpy"` in the `Gemfile`), editing the `Gemfile` and update the version number of the them gem, for example:
+    ```diff
+    - gem "jekyll-theme-chirpy", "~> 3.2", ">= 3.2.1"
+    + gem "jekyll-theme-chirpy", "~> 3.3", ">= 3.3.0"
+    ```
+
+    And then execute the following command:
+
+    ```console
+    $ bundle update jekyll-theme-chirpy
+    ```
+
+    As the version upgrades, the critical files (for details, see the [Startup Template][starter]) and configuration options will change. Please refer to the [Upgrade Guide](https://github.com/cotes2020/jekyll-theme-chirpy/wiki/Upgrade-Guide) to keep your repo's files in sync with the latest version of the theme.
+
+- If you forked from the source project (there will be `gemspec` in the `Gemfile` of your site), then merge the [latest upstream tags][latest-tag] into your Jekyll site to complete the upgrade.
+The merge is likely to conflict with your local modifications. Please be patient and careful to resolve these conflicts.
 
 ## Documentation
 
@@ -243,6 +237,9 @@ This work is published under [MIT](https://github.com/cotes2020/jekyll-theme-chi
 [starter]: https://github.com/cotes2020/chirpy-starter
 [use-starter]: https://github.com/cotes2020/chirpy-starter/generate
 [workflow]: https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/.github/workflows/pages-deploy.yml.hook
+[chirpy-4.1.0]: https://github.com/cotes2020/jekyll-theme-chirpy/releases/tag/v4.1.0
+[pages-src]: https://docs.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site
+[latest-tag]: https://github.com/cotes2020/jekyll-theme-chirpy/tags
 
 <!-- ReadMe links -->
 

_config.yml

@@ -3,8 +3,8 @@
 # Import the theme
 theme: jekyll-theme-chirpy
 
-# Only if your site type is GitHub Project sites and doesn't have a custom domain,
-# change below value to '/projectname'.
+# Change the following value to '/PROJECT_NAME' ONLY IF your site type is GitHub Pages Project sites
+# and doesn't have a custom domain.
 baseurl: ''
 
 # The language of the webpage › http://www.lingoes.net/en/translator/langcode.htm

_posts/2019-08-08-write-a-new-post.md

@@ -146,7 +146,7 @@ By default, the image is centered, but you can specify the position by using one
   ```
   {: .nolineno}
 
-> **Limitation**: Once you specify the position of an image, it is forbidden to add the image caption.
+> **Limitation**: Once the position of the image is specified, the image caption should not be added.
 
 ### Image shadow