Update the docs & reduce the image size.
This commit is contained in:
Cotes Chung
parent
a0f80debb1
commit
04ad7bf432
56
README.md
56
README.md
|
|
@ -40,10 +40,10 @@ A minimal, sidebar, responsive web design Jekyll theme, focusing on text present
|
|||
|
||||
## Installation
|
||||
|
||||
[Fork **Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/fork) on GitHub, and clone the fork to local by:
|
||||
[Fork **Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/fork) on GitHub, rename the repository to `USERNAME.github.io` (where `USERNAME` is your GitHub username), and then open terminal and clone the fork to local by:
|
||||
|
||||
```terminal
|
||||
$ git clone git@github.com:<username>/jekyll-theme-chirpy -b master --single-branch
|
||||
$ git clone https://github.com/USERNAME/USERNAME.github.io.git -b master --single-branch
|
||||
```
|
||||
|
||||
### Setting up the local envrionment
|
||||
|
|
@ -58,15 +58,15 @@ $ bundle install
|
|||
|
||||
`bundle` will automatically install all the dependencies specified by `Gemfile`.
|
||||
|
||||
In order to generate some extra files (*categories*, *tags* and *last modified list*), we need to use some tool scripts. And they require dependency package [yq](https://github.com/mikefarah/yq#install) to be installed. What's more, if your machine is running Debian or macOS, you also need to install [GNU coreutils](https://www.gnu.org/software/coreutils/):
|
||||
In order to generate some extra files (_categories_, _tags_ and _last modified list_), we need to use some tool scripts. And they require dependency package [yq](https://github.com/mikefarah/yq#install) to be installed. What's more, if your machine is running Debian or macOS, you also need to install [GNU coreutils](https://www.gnu.org/software/coreutils/).
|
||||
|
||||
- Debian
|
||||
- on Debian:
|
||||
|
||||
```console
|
||||
$ sudo apt-get install coreutils
|
||||
```
|
||||
|
||||
- macOS
|
||||
- on macOS:
|
||||
|
||||
```console
|
||||
$ brew install coreutils
|
||||
|
|
@ -84,7 +84,7 @@ Go to the root directory of the project and start initialization:
|
|||
$ 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.
|
||||
> **Note**: If you not intend to deploy it on GitHub Pages, append parameter option `--no-gh` at the end of the above command.
|
||||
|
||||
What it does is:
|
||||
|
||||
|
|
@ -121,51 +121,33 @@ Few days later, you may find that the file changes does not refresh in real time
|
|||
|
||||
### 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. 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.
|
||||
Assuming you have already gone through the [initialization](#initialization), you can now choose ONE of the following methods to deploy your website.
|
||||
|
||||
#### Deploy on GitHub Pages
|
||||
|
||||
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.
|
||||
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. 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.
|
||||
2. Unless you prefer to project sites, rename your repository to `<username>.github.io` on GitHub.
|
||||
3. Choose 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) for your GitHub Pages site.
|
||||
4. Visit your website at the address indicated by GitHub.
|
||||
1. Push any commit to `origin/master` 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 repository on GitHub and choose 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) throught _Settings_
|
||||
→ _Options_ → _GitHub Pages_:
|
||||
|
||||
|
||||
3. 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.
|
||||
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.
|
||||
|
||||
Commit the changes of your repository first, then run the publish script:
|
||||
|
||||
```console
|
||||
$ 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, then push to `origin/master`. Its output is similar to the following log:
|
||||
|
||||
```terminal
|
||||
[INFO] Success to update lastmod for 4 post(s).
|
||||
[INFO] Succeed! 3 category-pages created.
|
||||
[INFO] Succeed! 4 tag-pages created.
|
||||
[INFO] Published successfully!
|
||||
```
|
||||
|
||||
Lastly, enable the pages service according to the instructions of the platform you choose.
|
||||
|
||||
#### Deploy on Private Server
|
||||
|
||||
In the root of the source project, build your site by:
|
||||
Go to the root of the source project, build your site by:
|
||||
|
||||
```console
|
||||
$ bash tools/build.sh -d /path/to/site/
|
||||
```
|
||||
|
||||
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.
|
||||
The generated site files will be placed in folder `/path/to/site/`. Now you should upload those files to your web server.
|
||||
|
||||
### Documentation
|
||||
|
||||
|
|
|
|||
|
|
@ -74,7 +74,7 @@ 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, 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 }}).
|
||||
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 through `run.sh`, `build.sh` or `deploy.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
|
||||
|
||||
|
|
@ -134,7 +134,6 @@ image: /path/to/image-file
|
|||
---
|
||||
```
|
||||
|
||||
|
||||
## Pinned Posts
|
||||
|
||||
You can pin one or more posts to the top of the home page, and the fixed posts are sorted in reverse order according to their release date. Enable by:
|
||||
|
|
@ -145,7 +144,6 @@ pin: true
|
|||
---
|
||||
```
|
||||
|
||||
|
||||
## Code Block
|
||||
|
||||
Markdown symbols <code class="highlighter-rouge">```</code> can easily create a code block as following examples.
|
||||
|
|
@ -156,7 +154,7 @@ This is a common code snippet, without syntax highlight and line number.
|
|||
|
||||
## Specific Language
|
||||
|
||||
Using <code class="highlighter-rouge">```language</code> you will get code snippets with line Numbers and syntax highlight.
|
||||
Using <code class="highlighter-rouge">```language</code> you will get code snippets with line numbers and syntax highlight.
|
||||
|
||||
> **Note**: The Jekyll style `{% raw %}{%{% endraw %} highlight LANGUAGE {% raw %}%}{% endraw %}` or `{% raw %}{%{% endraw %} highlight LANGUAGE linenos {% raw %}%}{% endraw %}` are not allowed to be used in this theme !
|
||||
|
||||
|
|
|
|||
|
|
@ -10,10 +10,10 @@ pin: true
|
|||
|
||||
## Installation
|
||||
|
||||
[Fork **Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/fork) on GitHub, and clone the fork to local by:
|
||||
[Fork **Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/fork) on GitHub, rename the repository to `USERNAME.github.io` (where `USERNAME` is your GitHub username), and then open terminal and clone the fork to local by:
|
||||
|
||||
```terminal
|
||||
$ git clone git@github.com:<username>/jekyll-theme-chirpy -b master --single-branch
|
||||
$ git clone https://github.com/USERNAME/USERNAME.github.io.git -b master --single-branch
|
||||
```
|
||||
|
||||
### Setting up the local envrionment
|
||||
|
|
@ -28,15 +28,15 @@ $ bundle install
|
|||
|
||||
`bundle` will automatically install all the dependencies specified by `Gemfile`.
|
||||
|
||||
In order to generate some extra files (*categories*, *tags* and *last modified list*), we need to use some tool scripts. And they require dependency package [yq](https://github.com/mikefarah/yq#install) to be installed. What's more, if your machine is running Debian or macOS, you also need to install [GNU coreutils](https://www.gnu.org/software/coreutils/):
|
||||
In order to generate some extra files (_categories_, _tags_ and _last modified list_), we need to use some tool scripts. And they require dependency package [yq](https://github.com/mikefarah/yq#install) to be installed. What's more, if your machine is running Debian or macOS, you also need to install [GNU coreutils](https://www.gnu.org/software/coreutils/).
|
||||
|
||||
- Debian
|
||||
- on Debian:
|
||||
|
||||
```console
|
||||
$ sudo apt-get install coreutils
|
||||
```
|
||||
|
||||
- macOS
|
||||
- on macOS:
|
||||
|
||||
```console
|
||||
$ brew install coreutils
|
||||
|
|
@ -54,7 +54,7 @@ Go to the root directory of the project and start initialization:
|
|||
$ 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.
|
||||
> **Note**: If you not intend to deploy it on GitHub Pages, append parameter option `--no-gh` at the end of the above command.
|
||||
|
||||
What it does is:
|
||||
|
||||
|
|
@ -91,48 +91,30 @@ Few days later, you may find that the file changes does not refresh in real time
|
|||
|
||||
### 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. 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.
|
||||
Assuming you have already gone through the [initialization](#initialization), you can now choose ONE of the following methods to deploy your website.
|
||||
|
||||
#### Deploy on GitHub Pages
|
||||
|
||||
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.
|
||||
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. 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.
|
||||
2. Unless you prefer to project sites, rename your repository to `<username>.github.io` on GitHub.
|
||||
3. Choose 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) for your GitHub Pages site.
|
||||
4. Visit your website at the address indicated by GitHub.
|
||||
1. Push any commit to `origin/master` 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 repository on GitHub and choose 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) throught _Settings_
|
||||
→ _Options_ → _GitHub Pages_:
|
||||
|
||||
|
||||
3. 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.
|
||||
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.
|
||||
|
||||
Commit the changes of your repository first, then run the publish script:
|
||||
|
||||
```console
|
||||
$ 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, then push to `origin/master`. Its output is similar to the following log:
|
||||
|
||||
```terminal
|
||||
[INFO] Success to update lastmod for 4 post(s).
|
||||
[INFO] Succeed! 3 category-pages created.
|
||||
[INFO] Succeed! 4 tag-pages created.
|
||||
[INFO] Published successfully!
|
||||
```
|
||||
|
||||
Lastly, enable the pages service according to the instructions of the platform you choose.
|
||||
|
||||
#### Deploy on Private Server
|
||||
|
||||
In the root of the source project, build your site by:
|
||||
Go to the root of the source project, build your site by:
|
||||
|
||||
```console
|
||||
$ bash tools/build.sh -d /path/to/site/
|
||||
```
|
||||
|
||||
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.
|
||||
The generated site files will be placed in folder `/path/to/site/`. Now you should upload those files to your web server.
|
||||
|
|
|
|||
Binary file not shown.
|
Before Width: | Height: | Size: 230 KiB After Width: | Height: | Size: 52 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 13 KiB |
|
|
@ -43,10 +43,10 @@
|
|||
|
||||
## 安装
|
||||
|
||||
[Fork **Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/fork)，然后克隆到本地：
|
||||
[Fork **Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/fork)，把仓库改名为 `USERNAME.github.io`（其中 `USERNAME` 是你的 GitHub 用户名）， 然后克隆到本地：
|
||||
|
||||
```terminal
|
||||
$ git clone git@github.com:<username>/jekyll-theme-chirpy -b master --single-branch
|
||||
$ git clone https://github.com/USERNAME/USERNAME.github.io.git -b master --single-branch
|
||||
```
|
||||
|
||||
### 设置本地环境
|
||||
|
|
@ -61,7 +61,7 @@ $ bundle install
|
|||
|
||||
`bundle` 会自动安装 `Gemfile` 内指定的依赖插件。
|
||||
|
||||
为了生成一些额外的文件（Post 的分类、标签以及更新时间列表），需要用到一些脚本工具。而它们需要安装依赖包 [yq](https://github.com/mikefarah/yq#install)。另外，如果你电脑的操作系统是 Debian 或者 macOS，还需安装 [GNU coreutils](https://www.gnu.org/software/coreutils/)：
|
||||
为了生成一些额外的文件（Post 的 _分类_、_标签_ 以及 _更新时间列表_），需要用到一些脚本工具。而它们需要安装依赖包 [yq](https://github.com/mikefarah/yq#install)。另外，如果你电脑的操作系统是 Debian 或者 macOS，还需安装 [GNU coreutils](https://www.gnu.org/software/coreutils/)：
|
||||
|
||||
- Debian
|
||||
|
||||
|
|
@ -132,37 +132,19 @@ $ bash tools/run.sh
|
|||
|
||||
由于安全原因，GitHub Pages 的构建强制加了 `safe`参数，这导致了我们不能使用脚本工具去创建所需的附加页面。因此，我们可以使用 GitHub Actions 去构建站点，把站点文件存储在一个新分支上，再指定该分支作为 Pages 服务的源。
|
||||
|
||||
1. 推送任意一个 commit 到 `origin/master` 以触发 GitHub Actions workflow。一旦 build 完毕，远端将会自动出现一个新分支 `gh-pages` 用来存储构建的站点文件。
|
||||
2. 除非你是使用 project 站点, 否则重命名你的仓库为 `<username>.github.io`。
|
||||
3. 选择分支 `gh-pages` 作为 GitHub Pages 站点的[发布源](https://docs.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site).
|
||||
4. 按照 GitHub 指示的地址去访问你的网站。
|
||||
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):
|
||||
|
||||
|
||||
3. 按照 GitHub 指示的地址去访问你的网站。
|
||||
|
||||
#### 部署到其他 Pages 平台
|
||||
|
||||
在 GitHub 之外的平台，例如 GitLab，就没法享受 **GitHub Actions** 的便利了。不过先别慌，可以通过工具来弥补这个遗憾。
|
||||
在 GitHub 之外的平台，例如 GitLab，就没法享受 **GitHub Actions** 的便利了。因此我们需要在本地构建站点（或者在其他第三方 CI 平台），然后推送站点文件到服务器上。
|
||||
|
||||
先把本地仓库的 upstream 改为新平台的仓库地址，推送一发。以后每次更新内容后，提交 commit ，然后运行:
|
||||
|
||||
```console
|
||||
$ bash tools/publish.sh
|
||||
```
|
||||
|
||||
>**注**: *最后更新* 列表根据文章的 git 修改记录生成，所以运行前先把 `_posts` 目录的修改提交。
|
||||
|
||||
它会自动生成文章的 *最后修改日期* 和 *分类 / 标签* 页面，并自动提交一个 commit 并推送到 `origin/master` 。输出日志类似如下：
|
||||
|
||||
```terminal
|
||||
[INFO] Success to update lastmod for 4 post(s).
|
||||
[INFO] Succeed! 3 category-pages created.
|
||||
[INFO] Succeed! 4 tag-pages created.
|
||||
[INFO] Published successfully!
|
||||
```
|
||||
|
||||
最后，根据平台的说明文档为项目开启 Pages 服务。
|
||||
|
||||
#### 部署到私人服务器
|
||||
|
||||
在项目更目录，运行:
|
||||
在项目根目录，运行:
|
||||
|
||||
```console
|
||||
$ bash tools/build.sh -d /path/to/site/
|
||||
|
|
@ -178,7 +160,7 @@ $ bash tools/build.sh -d /path/to/site/
|
|||
|
||||
三人行必有我师，欢迎提报告 bug, 帮助改进代码质量，或者提交新功能。具体操作规则请参考 [贡献指南](../.github/CONTRIBUTING.md)，谢谢 🙏。
|
||||
|
||||
## 感谢
|
||||
## 鸣谢
|
||||
|
||||
这个主题的开发主要基于 [Jekyll](https://jekyllrb.com/) 生态、[Bootstrap](https://getbootstrap.com/)、[Font Awesome](https://fontawesome.com/) 和其他一些出色的工具 (相关文件中可以找到这些工具的版权信息).
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue