Update the tutorials.

This commit is contained in:
Cotes Chung 2020-04-13 00:38:56 +08:00
parent 99aadd61c1
commit 1209879bed
4 changed files with 88 additions and 71 deletions

View file

@ -1,14 +1,26 @@
# Chirpy
Language: **English** | [简体中文](docs/README_zh-CN.md)
🌏 English • [简体中文](docs/README_zh-CN.md)
[![Build Status](https://github.com/cotes2020/jekyll-theme-chirpy/workflows/build/badge.svg?event=push)](https://github.com/cotes2020/jekyll-theme-chirpy/actions?query=event%3Apush)
[![GitHub license](https://img.shields.io/github/license/cotes2020/jekyll-theme-chirpy.svg)](https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/LICENSE)
[![996.icu](https://img.shields.io/badge/link-996.icu-%23FF4D5B.svg)](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**
[![Devices Mockup](https://raw.githubusercontent.com/cotes2020/jekyll-theme-chirpy/master/assets/img/sample/devices-mockup.png)](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
[![Devices Mockup](https://raw.githubusercontent.com/cotes2020/jekyll-theme-chirpy/master/assets/img/sample/devices-mockup.png)](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

View file

@ -25,11 +25,11 @@ 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`.
- **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.
@ -42,16 +42,19 @@ 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:
```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
```yaml
---
layout: category
@ -61,6 +64,7 @@ category: CATEGORY_NAME # e.g. Insect
```
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

View file

@ -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

View file

@ -1,14 +1,26 @@
# Chirpy
语言: [English](../README.md) | **简体中文**
🌏 [English](../README.md) • 简体中文
[![Build Status](https://github.com/cotes2020/jekyll-theme-chirpy/workflows/build/badge.svg?event=push)](https://github.com/cotes2020/jekyll-theme-chirpy/actions?query=event%3Apush)
[![GitHub license](https://img.shields.io/github/license/cotes2020/jekyll-theme-chirpy.svg)](https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/LICENSE)
[![996.icu](https://img.shields.io/badge/link-996.icu-%23FF4D5B.svg)](https://996.icu)
一个不一样的 Jekyll 主题(内附神秘工具),采用响应式设计,方便记录、管理、分享你的知识和经验。
一个不一样的响应式设计 Jekyll 主题(内附神秘工具),采用响应式设计,方便记录、管理、分享你的知识和经验。
**功能一览**
[![Devices Mockup](https://raw.githubusercontent.com/cotes2020/jekyll-theme-chirpy/master/assets/img/sample/devices-mockup.png)](https://chirpy.cotes.info)
## 目录
* [功能预览](#功能预览)
* [安装](#安装)
* [运行指南](#运行指南)
* [参与贡献](#参与贡献)
* [感谢](#感谢)
* [赞助](#赞助)
* [许可证书](#许可证书)
## 功能预览
* 自动暗夜模式
* 文章最后修改日期
@ -24,24 +36,14 @@
* SEO 优化
* 网站性能优化
[![Devices Mockup](https://raw.githubusercontent.com/cotes2020/jekyll-theme-chirpy/master/assets/img/sample/devices-mockup.png)](https://chirpy.cotes.info)
## 目录
* [安装](#安装)
* [运行指南](#运行指南)
* [参与贡献](#参与贡献)
* [感谢](#感谢)
* [赞助](#赞助)
* [许可证书](#许可证书)
## 安装
### 准备工作
按照 [Jekyll 官方文档](https://jekyllrb.com/docs/installation/) 完成基础环境的安装 (RubyRubyGemBundler 和 Jekyll)。为了使用项目内免费提供的脚本工具,你还需要安装 [Python](https://www.python.org/downloads/)( >= 3.5) 和 [ruamel.yaml](https://pypi.org/project/ruamel.yaml/)。
按照 [Jekyll 官方文档](https://jekyllrb.com/docs/installation/) 完成基础环境的安装 (RubyRubyGemBundler 和 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