From 1209879bed2bc8e3032d9b74ba5bfb3ed803eb3e Mon Sep 17 00:00:00 2001 From: Cotes Chung <11371340+cotes2020@users.noreply.github.com> Date: Mon, 13 Apr 2020 00:38:56 +0800 Subject: [PATCH] Update the tutorials. --- README.md | 46 ++++++++++++------------- _posts/2019-08-08-write-a-new-post.md | 49 +++++++++++++++------------ _posts/2019-08-09-getting-started.md | 26 +++++++++----- docs/README_zh-CN.md | 38 +++++++++++---------- 4 files changed, 88 insertions(+), 71 deletions(-) diff --git a/README.md b/README.md index 1c4306e..ca2c2f7 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/_posts/2019-08-08-write-a-new-post.md b/_posts/2019-08-08-write-a-new-post.md index 138da40..a20caed 100644 --- a/_posts/2019-08-08-write-a-new-post.md +++ b/_posts/2019-08-08-write-a-new-post.md @@ -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 the posts is recorded as `seo.date_modified`, for example: +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: + ```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 diff --git a/_posts/2019-08-09-getting-started.md b/_posts/2019-08-09-getting-started.md index 6394475..9b51da8 100644 --- a/_posts/2019-08-09-getting-started.md +++ b/_posts/2019-08-09-getting-started.md @@ -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 diff --git a/docs/README_zh-CN.md b/docs/README_zh-CN.md index be67840..58b8c73 100644 --- a/docs/README_zh-CN.md +++ b/docs/README_zh-CN.md @@ -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/) 完成基础环境的安装 (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