mirror of
https://github.com/cotes2020/jekyll-theme-chirpy.git
synced 2025-12-18 05:41:31 +00:00
Update the docs for discarded tools
This commit is contained in:
Cotes Chung
@@ -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:
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user