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

Update the tutorials

Browse source
This commit is contained in:
Cotes Chung 2021-09-29 20:44:00 +08:00
parent 52f854a2da
commit f4d4065b1c
5 changed files with 215 additions and 194 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

132
README.md
View file

@ -55,58 +55,25 @@ A minimal, sidebar, responsive web design Jekyll theme that focuses on text pres
## Prerequisites ## 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 ## 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. There are two ways to create a new repository for this theme:
- **[Fork on GitHub](#fork-on-github)** - Convenient for custom development, but difficult to update, only suitable for web developers.
### 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 #### Option 1. Using the Chirpy Starter
gem "jekyll-theme-chirpy"
```
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 #### Option 2. Forking on GitHub
theme: jekyll-theme-chirpy
```
And then execute: [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.
```console
$ bundle
```
Next, go to the installed local theme path:
```console
$ cd "$(bundle info --path jekyll-theme-chirpy)"
```
And then copy the critical files (for details, see [starter project][starter]) from the theme's gem to your Jekyll site.
> ⚠️ **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.
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!
### Fork on GitHub
[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.)
Install gem dependencies by:
```console
$ bundle
```
And then execute: And then execute:
@ -114,18 +81,28 @@ And then execute:
$ bash tools/init.sh $ 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. > **Note**: If you don't want to deploy your site on GitHub Pages, append option `--no-gh` at the end of the above command.
What it does is: The above command will:
1. Remove some files or directories from your repository: 1. Removes some files or directories from your repository:
- `.travis.yml` - `.travis.yml`
- files under `_posts` - files under `_posts`
- folder `docs` - 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`. 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`.
3. Automatically create a commit to save the changes. 3. Removes item `Gemfile.lock` from `.gitignore`.
4. Creates a new commit to save the changes automatically.
### Installing Dependencies
Before running for the first time, go the root directory of your site, and install dependencies as follows:
```console
$ bundle
```
## Usage ## Usage
@ -142,7 +119,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. 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 ### Running Local Server
@ -154,14 +131,14 @@ $ bundle exec jekyll s
Or run the site on Docker with the following command: Or run the site on Docker with the following command:
```terminal ```console
$ docker run -it --rm \ $ docker run -it --rm \
--volume="$PWD:/srv/jekyll" \ --volume="$PWD:/srv/jekyll" \
-p 4000:4000 jekyll/jekyll \ -p 4000:4000 jekyll/jekyll \
jekyll serve 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 ### Deployment
@ -169,40 +146,47 @@ Before the deployment begins, checkout the file `_config.yml` and make sure the
Now you can choose ONE of the following methods to deploy your Jekyll site. 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: 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 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/test.sh` and `tools/deploy.sh`. Otherwise, copy them from this repo to your Jekyll site.
And then rename your repository to `<GH-USERNAME>.github.io` on GitHub. - Ensure your Jekyll site has file `tools/deploy.sh`. Otherwise, copy it from here to your Jekyll site.
- 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: 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. 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) ![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. 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 ```console
$ JEKYLL_ENV=production bundle exec jekyll b $ 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 \ $ docker run -it --rm \
--env JEKYLL_ENV=production \ --env JEKYLL_ENV=production \
--volume="$PWD:/srv/jekyll" \ --volume="$PWD:/srv/jekyll" \
@ -210,7 +194,28 @@ $ docker run -it --rm \
jekyll build 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 ## Documentation
@ -243,6 +248,9 @@ This work is published under [MIT](https://github.com/cotes2020/jekyll-theme-chi
[starter]: https://github.com/cotes2020/chirpy-starter [starter]: https://github.com/cotes2020/chirpy-starter
[use-starter]: https://github.com/cotes2020/chirpy-starter/generate [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 [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 --> <!-- ReadMe links -->

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

@ -146,7 +146,7 @@ By default, the image is centered, but you can specify the position by using one
``` ```
{: .nolineno} {: .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 ### Image shadow

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

@ -9,60 +9,25 @@ pin: true
## Prerequisites ## 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 ## 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. There are two ways to create a new repository for this theme:
- **[Fork on GitHub](#fork-on-github)** - Convenient for custom development, but difficult to update, only suitable for web developers.
### 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 #### Option 1. Using the Chirpy Starter
gem "jekyll-theme-chirpy"
```
{: .nolineno file='Gemfile' }
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 #### Option 2. Forking on GitHub
theme: jekyll-theme-chirpy
```
{: .nolineno file='_config.yml' }
And then execute: [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][latest-tag] and start writing.
```console
$ bundle
```
Next, go to the installed local theme path:
```console
$ cd "$(bundle info --path jekyll-theme-chirpy)"
```
And then copy the critical files (for details, see [starter project][starter]) from the theme's gem to your Jekyll site.
> ⚠️ **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.
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!
### Fork on GitHub
[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.)
Install gem dependencies by:
```console
$ bundle
```
And then execute: And then execute:
@ -70,18 +35,28 @@ And then execute:
$ bash tools/init.sh $ 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. > **Note**: If you don't want to deploy your site on GitHub Pages, append option `--no-gh` at the end of the above command.
What it does is: The above command will:
1. Remove some files or directories from your repository: 1. Removes some files or directories from your repository:
- `.travis.yml` - `.travis.yml`
- files under `_posts` - files under `_posts`
- folder `docs` - 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`. 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`.
3. Automatically create a commit to save the changes. 3. Removes item `Gemfile.lock` from `.gitignore`.
4. Creates a new commit to save the changes automatically.
### Installing Dependencies
Before running for the first time, go the root directory of your site, and install dependencies as follows:
```console
$ bundle
```
## Usage ## Usage
@ -98,7 +73,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. 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 ### Running Local Server
@ -110,14 +85,14 @@ $ bundle exec jekyll s
Or run the site on Docker with the following command: Or run the site on Docker with the following command:
```terminal ```console
$ docker run -it --rm \ $ docker run -it --rm \
--volume="$PWD:/srv/jekyll" \ --volume="$PWD:/srv/jekyll" \
-p 4000:4000 jekyll/jekyll \ -p 4000:4000 jekyll/jekyll \
jekyll serve 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 ### Deployment
@ -125,40 +100,47 @@ Before the deployment begins, checkout the file `_config.yml` and make sure the
Now you can choose ONE of the following methods to deploy your Jekyll site. 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: 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 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/test.sh` and `tools/deploy.sh`. Otherwise, copy them from this repo to your Jekyll site.
And then rename your repository to `<GH-USERNAME>.github.io` on GitHub. - Ensure your Jekyll site has file `tools/deploy.sh`. Otherwise, copy it from here to your Jekyll site.
- 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: 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. 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){: width="850" height="153" } ![gh-pages-sources](https://cdn.jsdelivr.net/gh/cotes2020/chirpy-images/posts/20190809/gh-pages-sources.png){: width="850" height="153" }
3. Visit your website at the address indicated by GitHub. 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 ```console
$ JEKYLL_ENV=production bundle exec jekyll b $ 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 \ $ docker run -it --rm \
--env JEKYLL_ENV=production \ --env JEKYLL_ENV=production \
--volume="$PWD:/srv/jekyll" \ --volume="$PWD:/srv/jekyll" \
@ -166,8 +148,34 @@ $ docker run -it --rm \
jekyll build 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"
```
{: .nolineno file="Gemfile" }
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.
[starter]: https://github.com/cotes2020/chirpy-starter [starter]: https://github.com/cotes2020/chirpy-starter
[use-starter]: https://github.com/cotes2020/chirpy-starter/generate [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 [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

4
_posts/2019-08-11-customize-the-favicon.md
View file

@ -6,7 +6,7 @@ categories: [Blogging, Tutorial]
tags: [favicon] tags: [favicon]
--- ---
The [favicons](https://www.favicon-generator.org/about/) of [**Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/) are placed in the directory `assets/img/favicons/`. You may need to replace them with your own. The following sections will guide you how to create and replace the default favicons. The [favicons](https://www.favicon-generator.org/about/) of [**Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/) are placed in the directory `assets/img/favicons/`. You may want to replace them with your own. The following sections will guide you how to create and replace the default favicons.
## Generate the favicon ## Generate the favicon
@ -21,7 +21,7 @@ Download the generated package, unzip and delete the following two from the extr
- `browserconfig.xml` - `browserconfig.xml`
- `site.webmanifest` - `site.webmanifest`
Now, copy the remaining image files (`PNG` and `ICO`) to cover the original files in the folder `assets/img/favicons/` of your Jekyll site. Now, copy the remaining image files (`PNG` and `ICO`) to cover the original files in the folder `assets/img/favicons/` of your Jekyll site. If your Jekyll site doesn't have this directory yet, just create one.
The following table will helps you understand the changes to the favicon files: The following table will helps you understand the changes to the favicon files:

135
docs/README.zh-CN.md
View file

@ -54,62 +54,27 @@
- SEO 优化 - SEO 优化
- 网站性能优化 - 网站性能优化
## 前提要求 ## 前提要求
参考 [Jekyll Docs](https://jekyllrb.com/docs/installation/) 安装 `Ruby`，`RubyGems`，`Jekyll` 和 `Bundler`。需要注意的是，`Ruby` 的版本必须与主题在 [RubyGems.org](https://rubygems.org/gems/jekyll-theme-chirpy) 上的要求一致. 参考 [Jekyll Docs](https://jekyllrb.com/docs/installation/) 安装 `Ruby`，`RubyGems`，`Jekyll` 和 `Bundler`。
## 安装 ## 安装
有二法可得此主题: ### 创建新仓库
- **[从 RubyGems 安装](#从-rubygems-安装)** - 易于版本升级，隔离无关的主题项目文件，让您的仓库舒适清爽。 有两种方式可以创建一个使用本主题的仓库：
- **[从 GitHub 上 Fork](#从-github-上-fork)** - 对个性化二次开发友好，但是难于升级，只适合专业开发人员使用。
### 从 RubyGems 安装 - **[使用 Chirpy Starter](#使用-chirpy-starter)** - 易于版本升级，隔离无关的主题项目文件，让您的仓库舒适清爽。
在您的 Jekyll 站点的 `Gemfile` 添加: - **[从 GitHub 上 Fork](#从-github-上-fork)** - 对个性化二次开发友好，但是难于升级。除非您决定魔改此款主题或者参与代码贡献，否则不推荐使用此方式。
```ruby #### 使用 Chirpy Starter
gem "jekyll-theme-chirpy"
```
然后，添加这行到您的 Jekyll 站点的 `_config.yml`: [使用 Chirpy Starter][use-starter] 来快速创建 Jekyll 站点，命名为 `<GH_USERNAME>.github.io`，其中 `GH_USERNAME` 是您的 GitHub username。
```yaml #### 从 GitHub 上 Fork
theme: jekyll-theme-chirpy
```
接着执行: [Fork **Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/fork) 并改名为 `<GH_USERNAME>.github.io`。友情提示：默认分支的代码处于开发状态，如果您想博客更加稳定，请切换到最新的 [Tag][latest-tag] 开始写作。
```console
$ bundle
```
然后，进入主题的 gem 目录:
```console
$ cd "$(bundle info --path jekyll-theme-chirpy)"
```
拷贝运行站点所需主题的 gem 文件（详见 [starter 仓库][starter] 的文件目录）至您的 Jekyll 站点, 然后把主题的 `_config.yml` 全部内容附加到您的 Jekyll 站点的同名文件。
> ⚠️ **留意重叠的文件！**
>
> 如果您的网站是通过命令 `jekyll new` 创建的，那么站点的根目录会存在文件 `index.markdown` 和 `about.markdown`。 请务必删除它们, 否则在网站构建后将覆盖主题的 `index.html` 和 `_tabs/about.html`，引起空白或错乱的页面出现。
作为替代方案，同时也被我们力荐，您可以 [使用 starter template][use-starter] 来快速创建 Jekyll 站点，以省去复制主题 gem 文件的时间。那里早已为您准备好建站需要的一切！
### 从 GitHub 上 Fork
[Fork **Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/fork) 然后克隆到本地。(友情提示：默认分支的代码处于开发状态，如果您想博客更加稳定，请切换到最新的 [Tag](https://github.com/cotes2020/jekyll-theme-chirpy/tags) 开始写作。)
安装依赖：
```console
$ bundle
```
接着执行文件初始化: 接着执行文件初始化:
@ -117,18 +82,28 @@ $ bundle
$ bash tools/init.sh $ bash tools/init.sh
``` ```
> 如果您不打算部署到 GitHub Pages, 在上述命令后附加参数选项 `--no-gh`。 > **注**：如果您不打算部署到 GitHub Pages， 在上述命令后附加参数选项 `--no-gh`。
上述脚本完成了以下工作: 上述脚本将会:
1. 从您的仓库中删除了: 1. 从您的仓库中删除了:
- `.travis.yml` - `.travis.yml`
- `_posts` 下的文件 - `_posts` 下的文件
- `docs` 目录 - `docs` 目录
2. 如果使用了参数 `--no-gh`，则会怒删 `.github`。否则，将会配置 GitHub Actions：把 `.github/workflows/pages-deploy.yml.hook` 的后缀 `.hook` 去除，然后删除 `.github` 里的其他目录和文件。 2. 如果使用了参数 `--no-gh`，则会怒删文件夹 `.github`。否则，配置 GitHub Actions：把 `.github/workflows/pages-deploy.yml.hook` 的后缀 `.hook` 去除，然后删除 `.github` 里的其他目录和文件。
3. 自动提交一个 Commit 以保存上述文件的更改。 3. 从 `.gitignore` 中删除 `Gemfile.lock`。
4. 自动提交一个 Commit 以保存上述文件的更改。
### 安装依赖：
首次运行本项目，需要先安装依赖：
```console
$ bundle
```
## 使用 ## 使用
@ -143,9 +118,9 @@ $ bash tools/init.sh
### 自定义样式 ### 自定义样式
如果您需要自定义样式, 拷贝主题的文件 `assets/css/style.scss` 到您站点的相同路径上，然后在该文件末尾添加样式。 如果您需要自定义样式， 拷贝主题的文件 `assets/css/style.scss` 到您站点的相同路径上，然后在该文件末尾添加样式。
自 `v4.1.0` 起，如果您想覆盖文件 `_sass/addon/variables.scss` 里定义的 SASS 变量的默认值，新建文件 `_sass/variables-hook.scss`，然后重写您需要的变量即可。 自 [`v4.1.0`][chirpy-4.1.0] 起，如果您想覆盖文件 `_sass/addon/variables.scss` 里定义的 SASS 变量的默认值，新建文件 `_sass/variables-hook.scss`，然后重写您需要的变量即可。
### 本地运行 ### 本地运行
@ -164,36 +139,43 @@ $ docker run -it --rm \
jekyll serve jekyll serve
``` ```
访问本地服务：<http://localhost:4000> 稍候片刻，即可访问本地服务：_<http://localhost:4000>_
### 部署 ### 部署
部署开始前，把 `_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`。 部署开始前，把 `_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`。
现在您可以选择下列其中一个方式去站点部署。 现在您可以选择下列其中一个方式去站点部署。
#### 部署到 GitHub Pages #### 使用 GitHub Actions 部署
由于安全原因，GitHub Pages 的构建强制加了 `safe`参数，这导致了我们不能使用插件去创建所需的附加页面。因此，我们可以使用 GitHub Actions 去构建站点，把站点文件存储在一个新分支上，再指定该分支作为 Pages 服务的源。 由于安全原因，默认的 GitHub Pages 的构建强制加了 `safe`参数，这导致了我们不能使用插件去创建所需的附加页面。因此，我们可以使用 GitHub Actions 去构建站点，把站点文件存储在一个新分支上，再指定该分支作为 Pages 服务的源。
快速检查 GitHub Actions 构建需要的文件: 快速检查 GitHub Actions 构建需要的文件:
- 确保您的 Jekyll 站点存在文件 `.github/workflows/pages-deploy.yml`。没有的话，新建并填入[示例工作流][workflow]的内容, 注意参数 `on.push.branches` 的值必须和您的仓库默认分支名相同。 - 确保您的 Jekyll 站点存在文件 `.github/workflows/pages-deploy.yml`。没有的话，新建并填入「[示例 Workflow][workflow]」的内容，注意参数 `on.push.branches` 的值必须和您的仓库默认分支名相同。
- 检查您的 Jekyll 站点是否有文件 `tools/test.sh` 和 `tools/deploy.sh`. 没有的话, 从本仓库拷贝到您的 Jekyll 项目.
在 GitHub 把您的仓库命名为 `<GH-USERNAME>.github.io`，然后开始发布： - 检查您的 Jekyll 站点是否有文件 `tools/deploy.sh`。没有的话， 从本仓库拷贝到您的 Jekyll 项目。
- 再者，如果您已经把文件 `Gemfile.lock` 提交到了仓库里面，并且您运行本项目的操作系统不是 Linux，需要添加新的平台信息：
```console
$ bundle lock --add-platform x86_64-linux
```
完成上述条目后，到 GitHub 把您的仓库命名为 `<GH-USERNAME>.github.io`，然后开始发布：
1. 推送任意一个 commit 到 `origin/master` 以触发 GitHub Actions workflow。一旦 build 完毕并且成功，远端将会自动出现一个新分支 `gh-pages` 用来存储构建的站点文件。 1. 推送任意一个 commit 到 `origin/master` 以触发 GitHub Actions workflow。一旦 build 完毕并且成功，远端将会自动出现一个新分支 `gh-pages` 用来存储构建的站点文件。
2. 回到 GitHub 上的仓库， 通过 _Settings_ → _Options_ → _GitHub Pages_ 选择分支 `gh-pages` 作为[_发布源_](https://docs.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site): 2. 回到 GitHub 上的仓库，选择标签 _Settings_ → 点击左侧导航栏的 _Pages_ → _GitHub Pages_ 选择分支 `gh-pages` 的 `/(root)` 作为「[发布源][pages-src]」:
![gh-pages-sources](https://cdn.jsdelivr.net/gh/cotes2020/chirpy-images/posts/20190809/gh-pages-sources.png) ![gh-pages-sources](https://cdn.jsdelivr.net/gh/cotes2020/chirpy-images/posts/20190809/gh-pages-sources.png)
3. 按照 GitHub 指示的地址去访问您的网站。 3. 按照 GitHub 指示的地址去访问您的网站。
#### 部署到其他 Pages 平台 #### 手动构建部署
在 GitHub 之外的平台，例如 GitLab，就没法享受 **GitHub Actions** 的便利了。因此我们需要在本地构建站点（或者在其他第三方 CI 平台），然后推送站点文件到服务器上。 在 GitHub 之外的平台，就没法享受 **GitHub Actions** 的便利了。因此您需要在本地构建站点，然后推送站点文件到服务器上。
在项目根目录，运行: 在项目根目录，运行:
@ -213,25 +195,45 @@ $ docker run -it --rm \
生成的静态文件将会在 `_site`， 把内部的文件上传到服务器即可。 生成的静态文件将会在 `_site`， 把内部的文件上传到服务器即可。
### 升级
这取决于您如何使用这个 theme：
- 如果您是使用 theme gem（`Gemfile` 会有 `gem "jekyll-theme-chirpy"`），编辑 `Gemfile` 并更新 them gem 的版本号，譬如：
```diff
- gem "jekyll-theme-chirpy", "~> 3.2", ">= 3.2.1"
+ gem "jekyll-theme-chirpy", "~> 3.3", ">= 3.3.0"
```
接着执行以下命令：
```console
$ bundle update jekyll-theme-chirpy
```
随着 theme 版本的升级，运行站点的必要文件（详见 [Chirpy Starter][starter]）以及配置选项会出现变化，请参阅「[升级指南](https://github.com/cotes2020/jekyll-theme-chirpy/wiki/Upgrade-Guide)」的改动细节去保持您仓库中的相关文件同步到最新版本。
- 如果您是以 fork 的方式使用（您站点的 `Gemfile` 会有 `gemspec`），那么合并上游 [最新的 tag][latest-tag] 到您的 Repo 以完成升级。期间很有可能会产生冲突 (conflicts)，请务必耐心谨慎地解决它们。
## 文档 ## 文档
若想要更多细节以及更佳的阅读体验，请参阅 [线上教程](https://chirpy.cotes.info/categories/tutorial/)。 与此同时，[Wiki](https://github.com/cotes2020/jekyll-theme-chirpy/wiki) 也有一份教程的拷贝。请注意，Demo 网站和 Wiki 上的文档都是基于最新的发行版本，而 `master` 分支的功能往往领先于现有文档。 若想要更多细节以及更佳的阅读体验，请参阅「[线上教程](https://chirpy.cotes.info/categories/tutorial/)」。 与此同时，「[Wiki](https://github.com/cotes2020/jekyll-theme-chirpy/wiki)」也有一份教程的拷贝。请注意，Demo 网站和 Wiki 上的文档都是基于最新的发行版本，而 `master` 分支的功能往往领先于现有文档。
## 参与贡献 ## 参与贡献
三人行必有我师，欢迎提报告 bug, 帮助改进代码质量，或者提交新功能。具体操作规则请参考 [贡献指南](../.github/CONTRIBUTING.md)，谢谢 🙏。 三人行必有我师，欢迎提报告 bug，帮助改进代码质量，或者提交新功能。具体操作规则请参考「[贡献指南](../.github/CONTRIBUTING.md)」，谢谢 🙏。
## 鸣谢 ## 鸣谢
这个主题的开发主要基于 [Jekyll](https://jekyllrb.com/) 生态、[Bootstrap](https://getbootstrap.com/)、[Font Awesome](https://fontawesome.com/) 和其他一些出色的工具 (相关文件中可以找到这些工具的版权信息)。头像和图标的设计来自于 [Clipart Max](https://www.clipartmax.com/middle/m2i8b1m2K9Z5m2K9_ant-clipart-childrens-ant-cute/)。 此款主题的开发主要基于 [Jekyll](https://jekyllrb.com/) 生态、[Bootstrap](https://getbootstrap.com/)、[Font Awesome](https://fontawesome.com/) 和其他一些出色的工具 (相关文件中可以找到这些工具的版权信息)。头像和图标的设计来自于 [Clipart Max](https://www.clipartmax.com/middle/m2i8b1m2K9Z5m2K9_ant-clipart-childrens-ant-cute/)。
: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、分享新点子或者启发了我写出更通俗易懂的文档。
还有，感谢 [JetBrains][jb] 提供开源 License！ 还有，感谢 [JetBrains][jb] 提供开源 License！
## 赞助 ## 赞助
如果您喜欢这个主题或者它对您有帮助，请考虑打赏作者，您的支持将会极大地鼓励作者，并帮助作者更好地维护项目！ 如果您喜欢此款主题或者它对您有帮助，请考虑打赏作者，您的支持将会极大地鼓励作者，并帮助作者更好地维护项目！
[![Buy Me a Coffee](https://img.shields.io/badge/-请作者喝杯咖啡-ff813f?logo=buy-me-a-coffee&logoColor=white)](https://www.buymeacoffee.com/coteschung) [![Buy Me a Coffee](https://img.shields.io/badge/-请作者喝杯咖啡-ff813f?logo=buy-me-a-coffee&logoColor=white)](https://www.buymeacoffee.com/coteschung)
[![Wechat Pay](https://img.shields.io/badge/-微信打赏作者-brightgreen?logo=wechat&logoColor=white)][cn-donation] [![Wechat Pay](https://img.shields.io/badge/-微信打赏作者-brightgreen?logo=wechat&logoColor=white)][cn-donation]
@ -244,6 +246,9 @@ $ docker run -it --rm \
[starter]: https://github.com/cotes2020/chirpy-starter [starter]: https://github.com/cotes2020/chirpy-starter
[use-starter]: https://github.com/cotes2020/chirpy-starter/generate [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 [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 --> <!-- ReadMe links -->