Update the tutorials.
This commit is contained in:
Cotes Chung
parent
99aadd61c1
commit
1209879bed
4 changed files with 88 additions and 71 deletions
46
README.md
46
README.md
|
|
@ -1,14 +1,26 @@
|
|||
# Chirpy
|
||||
|
||||
Language: **English** | [简体中文](docs/README_zh-CN.md)
|
||||
🌏 English • [简体中文](docs/README_zh-CN.md)
|
||||
|
||||
[](https://github.com/cotes2020/jekyll-theme-chirpy/actions?query=event%3Apush)
|
||||
[](https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/LICENSE)
|
||||
[](https://996.icu)
|
||||
|
||||
A minimal, sidebar, responsive web design Jekyll theme, focusing on text presentation. Aim to help you easily record and share your knowledge.
|
||||
A minimal, sidebar, responsive web design Jekyll theme, focusing on text presentation, aim to help you easily record and share your knowledge. [Live Demo »](https://chirpy.cotes.info)
|
||||
|
||||
**Features**
|
||||
[](https://chirpy.cotes.info)
|
||||
|
||||
## Table of Contents
|
||||
|
||||
* [Features](#features)
|
||||
* [Installing](#installing)
|
||||
* [Usage](#usage)
|
||||
* [Contributing](#contributing)
|
||||
* [Credits](#credits)
|
||||
* [Support](#support)
|
||||
* [License](#license)
|
||||
|
||||
## Features
|
||||
|
||||
* Configurable theme mode
|
||||
* Two-level Categories
|
||||
|
|
@ -23,25 +35,13 @@ A minimal, sidebar, responsive web design Jekyll theme, focusing on text present
|
|||
* GA Pageviews reporting (Advanced)
|
||||
* SEO and Performance Optimization
|
||||
|
||||
[](https://chirpy.cotes.info)
|
||||
|
||||
## Table of Contents
|
||||
|
||||
* [Installing](#installing)
|
||||
* [Usage](#usage)
|
||||
* [Contributing](#contributing)
|
||||
* [Credits](#credits)
|
||||
* [Support](#support)
|
||||
* [License](#license)
|
||||
|
||||
|
||||
## Installing
|
||||
|
||||
### Prerequisites
|
||||
|
||||
Follow the [Jekyll Docs](https://jekyllrb.com/docs/installation/) to complete the installtion of basic environment (`Ruby `, `RubyGems` and `Bundler`). In order to use the script tools to save time, we also need to install [Python](https://www.python.org/downloads/)(version 3.5 or abover) and [ruamel.yaml](https://pypi.org/project/ruamel.yaml/).
|
||||
Follow the [Jekyll Docs](https://jekyllrb.com/docs/installation/) to complete the installtion of basic environment (`Ruby `, `RubyGems` and `Bundler`).
|
||||
|
||||
In addition, if your machine is running Debian or macOS, make sure the [GNU coreutils](https://www.gnu.org/software/coreutils/) is installed. Otherwise, get it by:
|
||||
To improve the writing experience, we need to use some script tools. If your machine is running Debian or macOS, make sure that [GNU coreutils](https://www.gnu.org/software/coreutils/) is installed. Otherwise, install by:
|
||||
|
||||
* Debian
|
||||
|
||||
|
|
@ -61,12 +61,12 @@ $ brew install coreutils
|
|||
[Fork **Chirpy** from GitHub](https://github.com/cotes2020/jekyll-theme-chirpy/fork), then clone your forked repo to local:
|
||||
|
||||
```console
|
||||
$ git clone git@github.com:USER/jekyll-theme-chirpy.git
|
||||
$ git clone git@github.com:USER/jekyll-theme-chirpy.git -b master
|
||||
```
|
||||
|
||||
replace the `USER` above to your GitHub username.
|
||||
and replace the `USER` above to your GitHub username.
|
||||
|
||||
The first time you run or build the project on your machine, perform the installation of Jekyll plugins. Go to the root of repo and run:
|
||||
The first time you run or build the project on local machine, perform the installation of Jekyll plugins. Go to the root of repo and run:
|
||||
|
||||
```terminal
|
||||
$ bundle install
|
||||
|
|
@ -115,9 +115,9 @@ As mentioned above, some files or directories should be removed from your repo:
|
|||
- .github
|
||||
|
||||
|
||||
### Customization
|
||||
### Configuration
|
||||
|
||||
Basically, go to `_config.yml` and configure the variables as needed. Some of them are typical options:
|
||||
Generally, go to `_config.yml` and configure the variables as needed. Some of them are typical options:
|
||||
|
||||
* `url`
|
||||
|
||||
|
|
@ -144,7 +144,7 @@ Basically, go to `_config.yml` and configure the variables as needed. Some of th
|
|||
|
||||
### Run Locally
|
||||
|
||||
You may want to preview the site before publishing, so just run the script tool:
|
||||
You may want to preview the site content before publishing, so just run the script tool:
|
||||
|
||||
```terminal
|
||||
$ bash tools/run.sh
|
||||
|
|
|
|||
|
|
@ -25,33 +25,36 @@ tags: [TAG] # TAG names should always be lowercase
|
|||
|
||||
> **Note**: The posts' ***layout*** has been set to `post` by default, so there is no need to add the variable ***layout*** in Front Matter block.
|
||||
|
||||
- **Timezone of date**
|
||||
### Timezone of date
|
||||
|
||||
In order to accurately record the release date of a post, you should not only setup the `timezone` of `_config.yml` but also provide the the post's timezone in field `date` of its Front Matter block. Format: `+/-TTTT`, e.g. `+0800`.
|
||||
In order to accurately record the release date of a post, you should not only setup the `timezone` of `_config.yml` but also provide the the post's timezone in field `date` of its Front Matter block. Format: `+/-TTTT`, e.g. `+0800`.
|
||||
|
||||
- **Categories and Tags**
|
||||
### 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 `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. The number of such *category*/*tag* type pages is equal to the number of `categories`/`tags` for all posts, they must match perfectly.
|
||||
The list of posts belonging to the same category/tag is recorded on a separate page. The number of such *category*/*tag* type pages is equal to the number of `categories`/`tags` for all posts, they must match perfectly.
|
||||
|
||||
let's say there is a post with front matter:
|
||||
let's say there is a post with front matter:
|
||||
```yaml
|
||||
categories: [Animal, Insect]
|
||||
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:
|
||||
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:
|
||||
|
||||
```terminal
|
||||
jekyll-theme-chirpy
|
||||
├── categories
|
||||
│ ├── animal.html
|
||||
│ └── tutorial.html
|
||||
└── tags
|
||||
└── bee.html
|
||||
│ └── insect.html
|
||||
├── tags
|
||||
│ └── bee.html
|
||||
...
|
||||
```
|
||||
|
||||
and the content of a *category* type page is
|
||||
and the content of a *category* type page is
|
||||
|
||||
```yaml
|
||||
---
|
||||
layout: category
|
||||
|
|
@ -60,7 +63,8 @@ category: CATEGORY_NAME # e.g. Insect
|
|||
---
|
||||
```
|
||||
|
||||
the content of a *tag* type page is
|
||||
the content of a *tag* type page is
|
||||
|
||||
```yaml
|
||||
---
|
||||
layout: tag
|
||||
|
|
@ -69,20 +73,23 @@ 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, it will complain to you '404'). The good news is that we got a lovely script tool `_scripts/py/pages_generator.py` to finish the boring task. Basically we will use it via `tools/init.sh` instead of running it separately. Check out its use case [here]({{ "/posts/getting-started/#option-1-built-by-github-pages" | 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, it will complain to you '404'). The good news is that we got a lovely script tool `_scripts/sh/create_pages.sh` to finish the boring task. Basically we will use it via `tools/init.sh` instead of running it separately. Check out its use case [here]({{ "/posts/getting-started/#option-1-built-by-github-pages" | relative_url }}).
|
||||
|
||||
- **Last modified date**
|
||||
## Last modified date
|
||||
|
||||
The last modified date of a post is obtained according to its latest git commit date, and all the modified date of the posts should be stored in `_data/updates.yml`. For example:
|
||||
|
||||
The last modified date of the posts is recorded as `seo.date_modified`, for example:
|
||||
```yaml
|
||||
---
|
||||
seo:
|
||||
date_modified: 2020-01-04 17:05:41 +0800
|
||||
---
|
||||
-
|
||||
filename: getting-started # the post filename without date and extension
|
||||
lastmod: 2020-04-13 00:38:56 +0800 # the post last modified date
|
||||
-
|
||||
...
|
||||
```
|
||||
|
||||
This date is equal to the lastest git-commit date of the post file and can be automatically generated by the tool script `_scripts/py/update_posts_lastmod.py`. Similar to the other script `pages_generator.py` mentioned above, it is also be called from `tools/init.sh`, so it doesn't have to be used separately.
|
||||
You can choose to create this file manually, but as you may notice, the better approach is to let it be automatically generated by a tool script. And `_scripts/sh/dump_lastmod.py` was born for this! Similar to the another script `_scripts/sh/create_pages.sh` mentioned above, it is also be called from `tools/init.sh`, 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 articles.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
|
|
|
|||
|
|
@ -6,11 +6,11 @@ categories: [Blogging, Tutorial]
|
|||
tags: [getting started]
|
||||
---
|
||||
|
||||
## Preparation
|
||||
## Prerequisites
|
||||
|
||||
Follow the [Jekyll Docs](https://jekyllrb.com/docs/installation/) to complete the installtion of basic environment (Ruby, RubyGem, Bundler and Jekyll). In order to use the script tools to save time, we also need to install [Python](https://www.python.org/downloads/)(version 3.5 or abover) and [ruamel.yaml](https://pypi.org/project/ruamel.yaml/).
|
||||
Follow the [Jekyll Docs](https://jekyllrb.com/docs/installation/) to complete the installtion of basic environment (`Ruby `, `RubyGems` and `Bundler`).
|
||||
|
||||
In addition, if your machine is running Debian or macOS, make sure you have the [GNU coreutils](https://www.gnu.org/software/coreutils/) installed. Otherwise, get it by:
|
||||
To improve the writing experience, we need to use some script tools. If your machine is running Debian or macOS, make sure that [GNU coreutils](https://www.gnu.org/software/coreutils/) is installed. Otherwise, install by:
|
||||
|
||||
* Debian
|
||||
|
||||
|
|
@ -25,18 +25,26 @@ $ brew install coreutils
|
|||
```
|
||||
|
||||
|
||||
## Install Jekyll Plugins
|
||||
## Jekyll Plugins
|
||||
|
||||
Go to the root of repo and run:
|
||||
[Fork **Chirpy** from GitHub](https://github.com/cotes2020/jekyll-theme-chirpy/fork), then clone your forked repo to local:
|
||||
|
||||
```console
|
||||
$ git clone git@github.com:USER/jekyll-theme-chirpy.git -b master
|
||||
```
|
||||
|
||||
and replace the `USER` above to your GitHub username.
|
||||
|
||||
The first time you run or build the project on local machine, perform the installation of Jekyll plugins. Go to the root of repo and run:
|
||||
|
||||
```terminal
|
||||
$ bundle install
|
||||
```
|
||||
|
||||
`bundle` will install all the dependent Jekyll Plugins listed in file `Gemfile` automatically.
|
||||
`bundle` will automatically install all the dependent Jekyll Plugins that listed in the `Gemfile`.
|
||||
|
||||
|
||||
## File Structure
|
||||
## Directory Structure
|
||||
|
||||
The main files and related brief introductions are listed below.
|
||||
|
||||
|
|
@ -74,7 +82,7 @@ As mentioned above, some files or directories should be removed from your repo:
|
|||
|
||||
## Configuration
|
||||
|
||||
Basically, go to `_config.yml` and configure the variables as needed. Some of them are typical options:
|
||||
Generally, go to `_config.yml` and configure the variables as needed. Some of them are typical options:
|
||||
|
||||
* `url`
|
||||
|
||||
|
|
@ -101,7 +109,7 @@ Basically, go to `_config.yml` and configure the variables as needed. Some of th
|
|||
|
||||
## Run Locally
|
||||
|
||||
You may want to preview the site before publishing, so just run the script tool:
|
||||
You may want to preview the site content before publishing, so just run the script tool:
|
||||
|
||||
```terminal
|
||||
$ bash tools/run.sh
|
||||
|
|
|
|||
|
|
@ -1,14 +1,26 @@
|
|||
# Chirpy
|
||||
|
||||
语言: [English](../README.md) | **简体中文**
|
||||
🌏 [English](../README.md) • 简体中文
|
||||
|
||||
[](https://github.com/cotes2020/jekyll-theme-chirpy/actions?query=event%3Apush)
|
||||
[](https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/LICENSE)
|
||||
[](https://996.icu)
|
||||
|
||||
一个不一样的 Jekyll 主题（内附神秘工具），采用响应式设计，方便记录、管理、分享你的知识和经验。
|
||||
一个不一样的响应式设计 Jekyll 主题（内附神秘工具），采用响应式设计，方便记录、管理、分享你的知识和经验。
|
||||
|
||||
**功能一览**
|
||||
[](https://chirpy.cotes.info)
|
||||
|
||||
## 目录
|
||||
|
||||
* [功能预览](#功能预览)
|
||||
* [安装](#安装)
|
||||
* [运行指南](#运行指南)
|
||||
* [参与贡献](#参与贡献)
|
||||
* [感谢](#感谢)
|
||||
* [赞助](#赞助)
|
||||
* [许可证书](#许可证书)
|
||||
|
||||
## 功能预览
|
||||
|
||||
* 自动暗夜模式
|
||||
* 文章最后修改日期
|
||||
|
|
@ -24,24 +36,14 @@
|
|||
* SEO 优化
|
||||
* 网站性能优化
|
||||
|
||||
[](https://chirpy.cotes.info)
|
||||
|
||||
## 目录
|
||||
|
||||
* [安装](#安装)
|
||||
* [运行指南](#运行指南)
|
||||
* [参与贡献](#参与贡献)
|
||||
* [感谢](#感谢)
|
||||
* [赞助](#赞助)
|
||||
* [许可证书](#许可证书)
|
||||
|
||||
## 安装
|
||||
|
||||
### 准备工作
|
||||
|
||||
按照 [Jekyll 官方文档](https://jekyllrb.com/docs/installation/) 完成基础环境的安装 (Ruby，RubyGem，Bundler 和 Jekyll)。为了使用项目内免费提供的脚本工具，你还需要安装 [Python](https://www.python.org/downloads/)( >= 3.5) 和 [ruamel.yaml](https://pypi.org/project/ruamel.yaml/)。
|
||||
按照 [Jekyll 官方文档](https://jekyllrb.com/docs/installation/) 完成基础环境的安装 (Ruby，RubyGem，Bundler 和 Jekyll)。
|
||||
|
||||
如果你的机器系统是 Debian 或者 macOS，则需要确保安装了 [GNU coreutils](https://www.gnu.org/software/coreutils/)。否则，通过以下方式获得：
|
||||
为了使用项目内免费提供的脚本工具提升你的写作体验，如果你的机器系统是 Debian 或者 macOS，则需要确保安装了 [GNU coreutils](https://www.gnu.org/software/coreutils/)。否则，通过以下方式获得：
|
||||
|
||||
* Debian
|
||||
|
||||
|
|
@ -58,16 +60,16 @@
|
|||
接着，[fork](https://github.com/cotes2020/jekyll-theme-chirpy/fork) 一份代码，然后克隆你 Fork 的仓库到本地机器上。
|
||||
|
||||
```console
|
||||
$ git clone git@github.com:USER/jekyll-theme-chirpy.git
|
||||
$ git clone git@github.com:USER/jekyll-theme-chirpy.git -b master
|
||||
```
|
||||
|
||||
`USER` 替换为你的 GitHub username。
|
||||
把上述的`USER` 替换为你的 GitHub username。
|
||||
|
||||
|
||||
|
||||
### 安装 Jekyll 插件
|
||||
|
||||
在根目录下运行:
|
||||
本地首次运行或编译，请在项目根目录下运行:
|
||||
|
||||
```terminal
|
||||
$ bundle install
|
||||
|
|
|
|||
Loading…
Reference in a new issue