Update the docs for discarded tools

This commit is contained in:
Cotes Chung 2020-11-19 21:32:50 +08:00
parent 8fa1f3b497
commit ea56a900a0
6 changed files with 52 additions and 138 deletions

View file

@ -15,6 +15,5 @@ labels: question
- [ ] I searched the Internet for related problems, but still couldn't solve it.
- [ ] My question is based on the latest code of `master` branch.
## Description
<!-- Please describe your question. -->
<!-- Please describe your question in detial. -->

View file

@ -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/build.sh && bash ./tools/test.sh` (at the root of the project) locally and passed
- [ ] I have run `bash ./tools/test.sh --build` (at the root of the project) locally and passed
- [ ] I have tested this feature in the browser
### Test Configuration

View file

@ -58,32 +58,16 @@ $ 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/).
- on Debian:
```console
$ sudo apt-get install coreutils
```
- on macOS:
```console
$ brew install coreutils
```
### Setting up Docker environment (optional)
If you're a loyal fan of [**Docker**](https://www.docker.com/) or just too lazy to install the packages mentioned in [_Setting up the local envrionment_](#setting-up-the-local-envrionment), please make sure you have **Docker Engine** installed and running, and then get Docker image `jekyll/jekyll` from Docker Hub by the following command:
```console
$ docker pull jekyll/jekyll:latest
$ docker pull jekyll/jekyll
```
## 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.
### Initialization
Go to the root directory of the project and start initialization:
@ -120,26 +104,22 @@ Generally, go to `_config.yml` and configure the variables as needed. Some of th
You may want to preview the site contents before publishing, so just run it by:
```terminal
$ bash tools/run.sh
$ bundle exec jekyll s
```
Then open a browser and visit to <http://localhost:4000>.
Few days later, you may find that the file changes does not refresh in real time by using `run.sh`. Don't worry, the advanced option `-r` (or `--realtime`) will solve this problem, but it requires [**fswatch**](http://emcrisostomo.github.io/fswatch/) to be installed on your machine.
### Run on Docker
Run the site on Docker with the following command:
```terminal
$ docker run --rm -it \
$ docker run -it --rm \
--volume="$PWD:/srv/jekyll" \
-p 4000:4000 jekyll/jekyll \
bash tools/run.sh --docker
jekyll serve
```
Please note that on Docker containers, you'll lose the real-time refresh feature.
### 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`.
@ -148,7 +128,7 @@ Assuming you have already gone through the [initialization](#initialization), yo
#### 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 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 Pages service.
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.
@ -164,18 +144,17 @@ On platforms other than GitHub, we cannot enjoy the convenience of **GitHub Acti
Go to the root of the source project, build your site by:
```console
$ bash tools/build.sh
$ JEKYLL_ENV=production bundle exec jekyll b
```
> **Note**: The output path can be specified with the option `-d`.
Or, build the site with Docker by:
```terminal
$ docker run --rm -it \
$ docker run -it --rm \
--env JEKYLL_ENV=production \
--volume="$PWD:/srv/jekyll" \
jekyll/jekyll \
bash tools/build.sh --docker
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.

View file

@ -31,67 +31,13 @@ In order to accurately record the release date of a post, you should not only se
### Categories and Tags
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. 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:
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. For instance:
```yaml
categories: [Animal, Insect]
tags: bee
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:
```sh
.
├── categories
│   ├── animal.html # a category type page
│   └── insect.html
├── tags
  └── bee.html # a tag type page
...
```
and the content of a *category* type page is
```yaml
---
layout: category
title: CATEGORY_NAME # e.g. Insect
category: CATEGORY_NAME # e.g. Insect
---
```
the content of a *tag* type page is
```yaml
---
layout: tag
title: TAG_NAME # e.g. bee
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 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
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
-
filename: getting-started # the post filename without date and extension
lastmod: 2020-04-13 00:38:56 +0800 # the post last modified date
-
...
```
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 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 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/):
@ -102,7 +48,6 @@ toc: false
---
```
## Comments
Similar to TOC, the [Disqus](https://disqus.com/) comments is loaded by default in each post, and the global switch is defined by variable `comments` in file `_config.yml` . If you want to close the comment for specific post, add the following to the **Front Matter** of the post:
@ -113,7 +58,6 @@ comments: false
---
```
## Mathematics
For website performance reasons, the mathematical feature won't be loaded by default. But it can be enabled by:

View file

@ -28,32 +28,16 @@ $ 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/).
- on Debian:
```console
$ sudo apt-get install coreutils
```
- on macOS:
```console
$ brew install coreutils
```
### Setting up Docker environment (optional)
If you're a loyal fan of [**Docker**](https://www.docker.com/) or just too lazy to install the packages mentioned in [_Setting up the local envrionment_](#setting-up-the-local-envrionment), please make sure you have **Docker Engine** installed and running, and then get Docker image `jekyll/jekyll` from Docker Hub by the following command:
```console
$ docker pull jekyll/jekyll:latest
$ docker pull jekyll/jekyll
```
## 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.
### Initialization
Go to the root directory of the project and start initialization:
@ -90,13 +74,11 @@ Generally, go to `_config.yml` and configure the variables as needed. Some of th
You may want to preview the site contents before publishing, so just run it by:
```terminal
$ bash tools/run.sh
$ bundle exec jekyll s
```
Then open a browser and visit to <http://localhost:4000>.
Few days later, you may find that the file changes does not refresh in real time by using `run.sh`. Don't worry, the advanced option `-r` (or `--realtime`) will solve this problem, but it requires [**fswatch**](http://emcrisostomo.github.io/fswatch/) to be installed on your machine.
### Run on Docker
Run the site on Docker with the following command:
@ -105,10 +87,9 @@ Run the site on Docker with the following command:
$ docker run --rm -it \
--volume="$PWD:/srv/jekyll" \
-p 4000:4000 jekyll/jekyll \
bash tools/run.sh --docker
jekyll serve
```
Please note that on Docker containers, you'll lose the real-time refresh feature.
### Deployment
@ -118,7 +99,7 @@ Assuming you have already gone through the [initialization](#initialization), yo
#### 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 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 Pages service.
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.
@ -134,18 +115,17 @@ On platforms other than GitHub, we cannot enjoy the convenience of **GitHub Acti
Go to the root of the source project, build your site by:
```console
$ bash tools/build.sh
$ JEKYLL_ENV=production bundle exec jekyll b
```
> **Note**: The output path can be specified with the option `-d`.
Or, build the site with Docker by:
```terminal
$ docker run --rm -it \
$ docker run -it --rm \
--env JEKYLL_ENV=production \
--volume="$PWD:/srv/jekyll" \
jekyll/jekyll \
bash tools/build.sh --docker
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.

View file

@ -61,24 +61,17 @@ $ bundle install
`bundle` 会自动安装 `Gemfile` 内指定的依赖插件。
为了生成一些额外的文件Post 的 _分类_、_标签_ 以及 _更新时间列表_),需要用到一些脚本工具。而它们需要安装依赖包 [yq](https://github.com/mikefarah/yq#install)。另外,如果你电脑的操作系统是 Debian 或者 macOS还需安装 [GNU coreutils](https://www.gnu.org/software/coreutils/)
### 配置 Docker 镜像(可选)
- Debian
如果你是 [**Docker**](https://www.docker.com/) 的铁粉,或者不想在本地安装上述 [_设置本地环境_](#设置本地环境) 提到的包, 那么请确保先安装并运行了 **Docker Engine** 然后从 Docker Hub 获取镜像 `jekyll/jekyll`:
```console
$ sudo apt-get install coreutils
```
```console
$ docker pull jekyll/jekyll
```
- macOS
```console
$ brew install coreutils
```
## 使用
运行 [**Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/) 需要一些额外的文件, 它们不能通过 Jekyll 原生的命令生成,所以请严格依照下列说明去运行或部署此项目。
### 初始化
在项目根目录,开始初始化:
@ -112,15 +105,24 @@ $ bash tools/init.sh
### 本地运行
使用以下工具可轻松运行:
发布之前,在本地预览:
```terminal
$ bash tools/run.sh
$ bundle exec jekyll s
```
访问本地服务: <http://localhost:4000>
如果你想在本地服务运行后,把修改源文件的更改实时刷新,可使用选项 `-r` (或 `--realtime`),不过要先安装依赖 [**fswatch**](http://emcrisostomo.github.io/fswatch/) 。
### 用 Docker 运行
在项目根目录运行命令:
```terminal
$ docker run -it --rm \
--volume="$PWD:/srv/jekyll" \
-p 4000:4000 jekyll/jekyll \
jekyll serve
```
### 部署
@ -130,7 +132,7 @@ $ bash tools/run.sh
#### 部署到 GitHub Pages
由于安全原因GitHub Pages 的构建强制加了 `safe`参数,这导致了我们不能使用脚本工具去创建所需的附加页面。因此,我们可以使用 GitHub Actions 去构建站点,把站点文件存储在一个新分支上,再指定该分支作为 Pages 服务的源。
由于安全原因GitHub Pages 的构建强制加了 `safe`参数,这导致了我们不能使用插件去创建所需的附加页面。因此,我们可以使用 GitHub Actions 去构建站点,把站点文件存储在一个新分支上,再指定该分支作为 Pages 服务的源。
1. 推送任意一个 commit 到 `origin/master` 以触发 GitHub Actions workflow。一旦 build 完毕并且成功,远端将会自动出现一个新分支 `gh-pages` 用来存储构建的站点文件。
@ -147,10 +149,20 @@ $ bash tools/run.sh
在项目根目录,运行:
```console
$ bash tools/build.sh -d /path/to/site/
$ JEKYLL_ENV=production bundle exec jekyll b
```
生成的静态文件将会在 `/path/to/site/` 把内部的文件上传到服务器即可。
或者通过 Docker 构建:
```terminal
$ docker run -it --rm \
--env JEKYLL_ENV=production \
--volume="$PWD:/srv/jekyll" \
jekyll/jekyll \
jekyll build
```
生成的静态文件将会在 `_site` 把内部的文件上传到服务器即可。
### 文档