diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
new file mode 100644
index 0000000..ed84c5b
--- /dev/null
+++ b/.github/CONTRIBUTING.md
@@ -0,0 +1,22 @@
+# How to Contribute
+
+I want to thank you for sparing a time to improve this project! Here are some guidelines for contributing:
+
+## Bug Reporting
+
+If you found a bug, please ensure it doesn't appear in other existing [issues](https://github.com/cotes2020/jekyll-theme-chirpy/issues). After that, [create a new issues](https://github.com/cotes2020/jekyll-theme-chirpy/issues/new/choose) with template `Bug Report` and follow it's illustration to describe the situation.
+
+
+## Code Optimization
+
+If you are willing to improve some of the existing code, such as performance optimization, code simplification, or even correct spelling errors of variable names, please submit a new PR to help us.
+
+
+## Feature Request
+
+Basically, it is recommended to first submit a `Feature Request` issue to discuss whether your idea fits the project. Once the discussion is complete and the request is approved, fork this project, complete the development of new features, and submit a Pull Request. What's more, the PR should be merged into `master` branch without conflict.
+
+
+---
+
+:tada:Your volunteering will make the open source world more beautiful, thanks again!:tada:
\ No newline at end of file
diff --git a/README.md b/README.md
index 0855660..e1a284b 100644
--- a/README.md
+++ b/README.md
@@ -4,51 +4,84 @@
[![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)
-English | [中文](README_zh-CN.md)
+Language: English | [简体中文](docs/README_zh-CN.md)
-![devices-mockup](https://raw.githubusercontent.com/cotes2020/jekyll-theme-chirpy/master/assets/img/sample/devices-mockup.png)
+A minimal, portfolio, sidebar, bootstrap Jekyll theme with responsive web design and focuses on text exhibition. It will help you easily record, manage and share your knowledge and experience.
-A minimal, portfolio, sidebar, bootstrap Jekyll theme with responsive web design and focuses on text exhibition. It will help you easily record, manage and share your knowledge and experience. Hope you like it! [**Live Demo** »](https://chirpy.cotes.info)
-
-
-## Features
+You will get the following features:
* Auto Dark Mode
* Posts' Last Modified Date
* Table of Contents
-* Recommand Related Post Automatically
-* Disqus Comments
+* Automatically Recommend Related Posts
* Syntax highlighting
* Two Level Categories
* Search
-* HTML Compress
* Atom Feeds
+* Disqus Comments
* Google Analytics
* GA Pageviews (Advanced)
* SEO Tag
* Performance Optimization
-## Quick Start
+[**Live Demo** »](https://chirpy.cotes.info)
-### Preparation
+![devices-mockup](https://raw.githubusercontent.com/cotes2020/jekyll-theme-chirpy/master/assets/img/sample/devices-mockup.png)
-Follow the [Jekyll Docs](https://jekyllrb.com/docs/installation/) to complete the installtion of basic environment (Ruby, RubyGem, Bundler and Jekyll). In addition, to use the funny script tools, 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/).
+## Table of Contents
-Next, [fork](https://github.com/cotes2020/jekyll-theme-chirpy/fork) **Chirpy** and then clone your forked repo locally.
+* [Getting Started](#getting-started)
+* [Usage](#usage)
+* [Contributing](#contributing)
+* [Credits](#credits)
+* [Support](#support)
+* [License](#license)
-### Install Jekyll Plugins
+## Getting Started
-Go to the root of repo and run:
+### 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/).
+
+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:
+
+* Debian
+
+```console
+$ sudo apt-get install coreutils
+```
+
+* macOS
+
+```console
+$ brew install coreutils
+```
+
+
+### Installing
+
+[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
+```
+
+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:
```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
+## Usage
+
+
+### Directory Structure
The main files and related brief introductions are listed below.
@@ -72,6 +105,7 @@ jekyll-theme-chirpy/
├── README.md
├── _config.yml # configuration file
├── tools # script tools
+├── docs
├── feed.xml
├── index.html
├── robots.txt
@@ -86,28 +120,18 @@ As mentioned above, some files or directories should be removed from your repo:
- _scripts/travis
-### Configuration
+### Customization
-Customize the variables in file `_config.yml` as needed.
+Basically, go to `_config.yml` and customize the variables as needed, some of them are typical options:
* Avatar
- The sample avatar is `/assets/img/sample/avatar.jpg`. It should be replaced by your own one. Notice that a huge image file will increase the load time of your site, so keep your avatar size as samll as possible(may be ** will help).
+ `avatar` defines the source image location. The sample image is `/assets/img/sample/avatar.jpg`. It should be replaced by your own one. Notice that a huge image file will increase the load time of your site, so keep your avatar size as samll as possible(may be ** will help).
* TimeZone
To ensure that the posts' release date matches the city you live in, please modify the field `timezone` correctly. A list of all available values can be found on [TimezoneConverter](http://www.timezoneconverter.com/cgi-bin/findzone/findzone) or [Wikipedia](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
-* Atom Feed
-
- The Atom feed url of your site will be:
-
- ```
- /feed.xml
- ```
-
- The `SITE_URL` was defined by variable `url` of `_config.yml`.
-
### Run Locally
@@ -117,11 +141,9 @@ You may want to preview the site before publishing, so just run the script tool:
$ bash tools/run.sh
```
->**Note**: The *Recent Update* list requires the latest git-log date of posts, thus make sure the changes in `_posts` have been committed before running this command.
+Open a modern brower and visit at .
-Open a brower and visit .
-
-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.
+Few days later, you may find that the file modification(e.g. edits to a post) 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. Type `-h` for more information.
### Deploying to GitHub Pages
@@ -142,10 +164,12 @@ By deploying the site in this way, you're allowed to push the source code direct
**2**. Commit the changes of the repo first, then run the initialization script:
-```console
+```terminal
$ bash tools/init.sh
```
+>**Note**: The *Recent Update* requires the posts' latest git-log date, so make sure the changes in `_posts` have been committed before running this command.
+
it will automatically generates the *Latest Modified Date* and *Categories / Tags* page for the posts.
**3**. Push the changes to `origin/master` then go to GitHub website and enable GitHub Pages service for the repo.
@@ -192,17 +216,27 @@ The generated static files will be placed in the root of `/path/to/local/project
and enjoy!
+### Documentation
-## Documentation
+For more details and the better reading experience, please check out the [tutorial in demo site](https://chirpy.cotes.info/categories/tutorial/). In the meanwhile, a copy of the tutorial is also available on the [Wiki](https://github.com/cotes2020/jekyll-theme-chirpy/wiki).
-For more information, please check out the [tutorial](https://chirpy.cotes.info/categories/tutorial/). In the meanwhile, a copy of the tutorial is also available on the [Wiki](https://github.com/cotes2020/jekyll-theme-chirpy/wiki).
+## Contributing
-## Sponsor
+The old saying: "Tow heads are better than one. Five heads are better than two." So, welcome to report bugs, improve code quality or submit a new feature. For more information, see [contributing guidelines](.github/CONTRIBUTING.md).
-Want to buy me a coffee? Click the button ❤️Sponsor at the top of the [Home Page](https://github.com/cotes2020/jekyll-theme-chirpy) and choose a link that suits you to donate. I'd really appreciate it and take it as encouragement to work on better projects.
+## Credits
+
+This theme is mainly built with [Jekyll](https://jekyllrb.com/) ecosystem, [Bootstrap](https://getbootstrap.com/), [Font Awesome](https://fontawesome.com/) and some other wonderful tools(their copyright information can be found in the relevant files).
+
+:tada:Thanks to all the volunteers who contributed to this project, their github ID is on [this list](https://github.com/cotes2020/jekyll-theme-chirpy/graphs/contributors). Also, I won't forget the guys who submitted the issues(or unmerged PR), they reported bugs, shared ideas or inspired me to write more readable documentation.
+
+
+## Support
+
+If you enjoy this theme or find it helpful, please consider becoming my sponsor, I'd really appreciate it! Click the button :heart:Sponsor at the top of the [Home Page](https://github.com/cotes2020/jekyll-theme-chirpy) and choose a link that suits you to donate. This will encourage me and help me maintain this project.
## License
-This work is published under [MIT](https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/LICENSE) License.
+This work is published under [MIT](https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/LICENSE) License.
\ No newline at end of file
diff --git a/_config.yml b/_config.yml
index f99c78a..ebaae66 100644
--- a/_config.yml
+++ b/_config.yml
@@ -168,6 +168,7 @@ exclude:
- Gemfile.lock
- Gemfile
- tools
+ - docs
sitemap_exclude: # Sitemap will exclude the following items.
fuzzy:
diff --git a/_posts/2019-08-09-getting-started.md b/_posts/2019-08-09-getting-started.md
index de7aa75..56fd327 100644
--- a/_posts/2019-08-09-getting-started.md
+++ b/_posts/2019-08-09-getting-started.md
@@ -7,9 +7,21 @@ tags: [getting started]
## Preparation
-Follow the [Jekyll Docs](https://jekyllrb.com/docs/installation/) to complete the installtion of basic environment (Ruby, RubyGem, Bundler and Jekyll). In addition, to use the funny script tools, 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, 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/).
-Next, [fork](https://github.com/cotes2020/jekyll-theme-chirpy/fork) **Chirpy** and then clone your forked repo locally.
+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:
+
+* Debian
+
+```console
+$ sudo apt-get install coreutils
+```
+
+* macOS
+
+```console
+$ brew install coreutils
+```
## Install Jekyll Plugins
@@ -73,16 +85,6 @@ Customize the variables in file `_config.yml` as needed.
To ensure that the posts' release date matches the city you live in, please modify the field `timezone` correctly. A list of all available values can be found on [TimezoneConverter](http://www.timezoneconverter.com/cgi-bin/findzone/findzone) or [Wikipedia](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
-* Atom Feed
-
- The Atom feed url of your site will be:
-
- ```
- /feed.xml
- ```
-
- The `SITE_URL` was defined by variable `url` of `_config.yml`.
-
## Run Locally
@@ -92,8 +94,6 @@ You may want to preview the site before publishing, so just run the script tool:
$ bash tools/run.sh
```
->**Note**: The *Recent Update* list requires the latest git-log date of posts, thus make sure the changes in `_posts` have been committed before running this command.
-
Open a brower and visit .
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.
@@ -122,6 +122,8 @@ By deploying the site in this way, you're allowed to push the source code direct
$ bash tools/init.sh
```
+> Please note that the *Recent Update* list requires the latest git-log date of posts, thus make sure the changes in `_posts` have been committed before running this command.
+
it will automatically generates the *Latest Modified Date* and *Categories / Tags* page for the posts.
**3**. Push the changes to `origin/master` then go to GitHub website and enable GitHub Pages service for the repo.
diff --git a/README_zh-CN.md b/docs/README_zh-CN.md
similarity index 60%
rename from README_zh-CN.md
rename to docs/README_zh-CN.md
index 3576e46..6d3ab38 100644
--- a/README_zh-CN.md
+++ b/docs/README_zh-CN.md
@@ -4,38 +4,67 @@
[![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)
-[English](README.md) | 中文
+Language: [English](../README.md) | 简体中文
-![devices-mockup](https://raw.githubusercontent.com/cotes2020/jekyll-theme-chirpy/master/assets/img/sample/devices-mockup.png)
+一个不一样的 Jekyll 主题(内附神秘工具),采用响应式设计,方便记录、管理、分享你的知识和经验。
-
-一个不一样的 Jekyll 主题,采用响应式设计,方便记录、管理、分享你的知识和经验。[**在线 Demo** »](https://chirpy.cotes.info)
-
-
-## 功能预览
+**功能一览**
* 自动暗夜模式
* 文章最后修改日期
* 文章目录
* 自动推荐相关文章
-* Disqus 评论
* 语法高亮
* 二级目录
* 搜索
-* HTML 压缩
* Atom 订阅
+* Disqus 评论
* Google 分析
-* 浏览数展示(高级功能)
+* GA 浏览报告(高级功能)
* SEO 优化
* 网站性能优化
+[**在线体验** »](https://chirpy.cotes.info)
+
+![devices-mockup](https://raw.githubusercontent.com/cotes2020/jekyll-theme-chirpy/master/assets/img/sample/devices-mockup.png)
+
+## 目录
+
+* [开始](#开始)
+* [运行指南](#运行指南)
+* [参与贡献](#参与贡献)
+* [感谢](#感谢)
+* [赞助](#赞助)
+* [许可证书](#许可证书)
+
## 开始
### 准备工作
-按照 [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)。为了使用项目内免费提供的脚本工具,你还需要安装 [Python](https://www.python.org/downloads/)( >= 3.5) 和 [ruamel.yaml](https://pypi.org/project/ruamel.yaml/)。
+
+如果你的机器系统是 Debian 或者 macOS,则需要确保安装了 [GNU coreutils](https://www.gnu.org/software/coreutils/)。否则,通过以下方式获得:
+
+* Debian
+
+ ```console
+ $ sudo apt-get install coreutils
+ ```
+
+* macOS
+
+ ```console
+ $ brew install coreutils
+ ```
+
+接着,[fork](https://github.com/cotes2020/jekyll-theme-chirpy/fork) 一份代码,然后克隆你 Fork 的仓库到本地机器上。
+
+```console
+$ git clone git@github.com:USER/jekyll-theme-chirpy.git
+```
+
+`USER` 替换为你的 GitHub username。
-接着,[fork](https://github.com/cotes2020/jekyll-theme-chirpy/fork) 一份代码,然后克隆你的 Fork 版到本地机器上。
### 安装 Jekyll 插件
@@ -48,6 +77,9 @@ $ bundle install
`bundle` 命令会自动安装 `Gemfile` 内声明的依赖插件.
+
+## 运行指南
+
### 文件目录
下面是主要的文件目录:
@@ -72,6 +104,7 @@ jekyll-theme-chirpy/
├── README.md
├── _config.yml # configuration file
├── tools # script tools
+├── docs
├── feed.xml
├── index.html
├── robots.txt
@@ -98,16 +131,6 @@ jekyll-theme-chirpy/
时区由 `timezone` 定义,默认为 `亚洲/上海`,如果肉身翻墙要换城市可在此列表找到: [TimezoneConverter](http://www.timezoneconverter.com/cgi-bin/findzone/findzone) 或者 [Wikipedia](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
-* Atom 订阅
-
- Atom 订阅路径是:
-
- ```
- /feed.xml
- ```
-
- `SITE_URL` 由变量 `url` 定义。
-
### 本地运行
@@ -117,8 +140,6 @@ jekyll-theme-chirpy/
$ bash tools/run.sh
```
->**注**: *最后更新* 列表根据文章的 git 修改记录生成, 所以运行前先把 `_posts` 目录的修改提交.
-
访问本地服务:
如果你想在本地服务运行后,把修改源文件的更改实时刷新,可使用选项 `-r` (或 `--realtime`),不过要先安装依赖 [**fswatch**](http://emcrisostomo.github.io/fswatch/) 。
@@ -138,14 +159,16 @@ $ bash tools/run.sh
|站点类型 | 仓库名称|
|:---|:---|
|User or Organization | `.github.io`|
-|Project| `.github.io` 以外的名字, 譬如 `project`|
+|Project| `.github.io` 以外的名字,譬如 `project`|
-**2**. 提交本地更改, 然后运行:
+**2**. 提交本地更改,然后运行:
```console
$ bash tools/init.sh
```
+>**注**: *最后更新* 列表根据文章的 git 修改记录生成,所以运行前先把 `_posts` 目录的修改提交。
+
它会自动生成文章的 *最后修改日期* 和 *分类 / 标签* 页面.
**3**. 推送到 `origin/master` 然后到 GitHub 网页为该项目开启 Pages 服务。
@@ -162,7 +185,7 @@ $ bash tools/init.sh
由于安全原因,GitHub Pages 不允许第三方插件运行,如果你想突破规则,就要本地构建站点内容。
-**1**. 到 GitHub 网页, 创建一个新的仓库,根据以下规则命名:
+**1**. 到 GitHub 网页,创建一个新的仓库,根据以下规则命名:
|站点类型 | 仓库名称|
|:---|:---|
@@ -178,7 +201,7 @@ $ bash tools/build.sh -d /path/to/local/project/
```
> `project` 为新仓库名称。
-如果你想使用 Project 网站, 修改配置文件的 `baseurl` 为项目名称, 以斜杠开头,如:`/project`。或者,在上述命令行后面加参数`-b /project`,`project` 替换为新仓库名称。
+如果你想使用 Project 网站,修改配置文件的 `baseurl` 为项目名称,以斜杠开头,如:`/project`。或者,在上述命令行后面加参数`-b /project`,`project` 替换为新仓库名称。
生成的静态文件将会在 `/path/to/local/project`. 把新仓库的修改提交并推送到远端 `master` 分支.
@@ -192,15 +215,28 @@ $ bash tools/build.sh -d /path/to/local/project/
|Project| `https://.github.io/project/`|
-## 文档
+### 文档
+
+更多细节及更佳的阅读体验,请参阅 [线上教程](https://chirpy.cotes.info/categories/tutorial/)。 与此同时,[Wiki](https://github.com/cotes2020/jekyll-theme-chirpy/wiki) 也有一份教程的拷贝。
+
+
+## 参与贡献
+
+三人行必有我师,欢迎提报告 bug, 帮助改进代码质量,或者提交新功能。具体操作规则请参考[此文](.github/CONTRIBUTING.md),谢谢🙏。
+
+## 感谢
+
+这个主题的开发主要基于 [Jekyll](https://jekyllrb.com/) 生态、[Bootstrap](https://getbootstrap.com/)、[Font Awesome](https://fontawesome.com/) 和其他一些出色的工具 (相关文件中可以找到这些工具的版权信息).
+
+:tada:感谢所有参与代码贡献的小伙伴, 他们的 GayHub ID 在这个[列表](https://github.com/cotes2020/jekyll-theme-chirpy/graphs/contributors)。 另外, 提交过 issues(或者未被合并 PR)的高富帅和白富美也不会被遗忘,他/她们帮助报告 bug、分享新点子或者启发了我写出更通俗易懂的文档。
-更多细节及更佳的阅读体验, 请参阅 [线上教程](https://chirpy.cotes.info/categories/tutorial/)。 与此同时, [Wiki](https://github.com/cotes2020/jekyll-theme-chirpy/wiki) 也有一份教程的拷贝.
## 赞助
-想要打赏作者吗?在 [项目主页](https://github.com/cotes2020/jekyll-theme-chirpy) 点击按钮 ❤️Sponsor 选择 *支付宝、微信* 链接 即可完成,您的打赏将会鼓励作者去更好地完成开源项目!
+如果您喜欢这个主题或者它对您有帮助,请考虑打赏作者:在 [项目主页](https://github.com/cotes2020/jekyll-theme-chirpy) 点击按钮 :heart:Sponsor 选择适合的链接即可完成(国内一般选第二个链接,支付宝/微信赞助),您的打赏将会极大地鼓励作者,并帮助作者更好地维护项目!
-## License 许可
+
+## 许可证书
本项目开源,基于 [MIT](https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/LICENSE) 许可。