From ea56a900a08405c5acaeb834c6228a28f2a7ea30 Mon Sep 17 00:00:00 2001 From: Cotes Chung <11371340+cotes2020@users.noreply.github.com> Date: Thu, 19 Nov 2020 21:32:50 +0800 Subject: [PATCH] Update the docs for discarded tools --- .github/ISSUE_TEMPLATE/question.md | 3 +- .github/PULL_REQUEST_TEMPLATE.md | 4 +- README.md | 39 ++++------------- _posts/2019-08-08-write-a-new-post.md | 60 +-------------------------- _posts/2019-08-09-getting-started.md | 36 ++++------------ docs/README_zh-CN.md | 48 +++++++++++++-------- 6 files changed, 52 insertions(+), 138 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/question.md b/.github/ISSUE_TEMPLATE/question.md index 7a21b07..d2fe2e0 100644 --- a/.github/ISSUE_TEMPLATE/question.md +++ b/.github/ISSUE_TEMPLATE/question.md @@ -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 - \ No newline at end of file + diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 4a9d106..9c1fbaf 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -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 @@ -41,4 +41,4 @@ Please describe the tests that you ran to verify your changes. Provide instructi - [ ] I have made corresponding changes to the documentation - [ ] My changes generate no new warnings - [ ] I have added tests that prove my fix is effective or that my feature works -- [ ] Any dependent changes have been merged and published in downstream modules \ No newline at end of file +- [ ] Any dependent changes have been merged and published in downstream modules diff --git a/README.md b/README.md index e10174c..92bd127 100644 --- a/README.md +++ b/README.md @@ -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 . -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. diff --git a/_posts/2019-08-08-write-a-new-post.md b/_posts/2019-08-08-write-a-new-post.md index 91b4559..963be9b 100644 --- a/_posts/2019-08-08-write-a-new-post.md +++ b/_posts/2019-08-08-write-a-new-post.md @@ -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: diff --git a/_posts/2019-08-09-getting-started.md b/_posts/2019-08-09-getting-started.md index b196e9b..998e117 100644 --- a/_posts/2019-08-09-getting-started.md +++ b/_posts/2019-08-09-getting-started.md @@ -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 . -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. diff --git a/docs/README_zh-CN.md b/docs/README_zh-CN.md index 8314674..66f7a61 100644 --- a/docs/README_zh-CN.md +++ b/docs/README_zh-CN.md @@ -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 ``` 访问本地服务： -如果你想在本地服务运行后，把修改源文件的更改实时刷新，可使用选项 `-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`， 把内部的文件上传到服务器即可。 ### 文档