Updated README and tutorial.

Formatted README.
This commit is contained in:
Cotes Chung 2020-01-09 20:24:44 +08:00
parent 12bacea674
commit b0d6513b7c
5 changed files with 181 additions and 86 deletions

22
.github/CONTRIBUTING.md vendored Normal file
View file

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

112
README.md
View file

@ -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 *<https://tinypng.com/>* 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 *<https://tinypng.com/>* 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:
```
<SITE_URL>/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 <http://localhost:4000>.
Open a brower and visit <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.
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,15 +216,25 @@ 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 <kbd>Sponsor</kbd> 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 <kbd>:heart:Sponsor</kbd> 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

View file

@ -168,6 +168,7 @@ exclude:
- Gemfile.lock
- Gemfile
- tools
- docs
sitemap_exclude: # Sitemap will exclude the following items.
fuzzy:

View file

@ -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:
```
<SITE_URL>/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 <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.
@ -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.

View file

@ -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/) 完成基础环境的安装 (RubyRubyGemBundler 和 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 订阅路径是:
```
<SITE_URL>/feed.xml
```
`SITE_URL` 由变量 `url` 定义。
### 本地运行
@ -117,8 +140,6 @@ jekyll-theme-chirpy/
$ bash tools/run.sh
```
>**注**: *最后更新* 列表根据文章的 git 修改记录生成, 所以运行前先把 `_posts` 目录的修改提交.
访问本地服务: <http://localhost:4000>
如果你想在本地服务运行后,把修改源文件的更改实时刷新,可使用选项 `-r` (或 `--realtime`),不过要先安装依赖 [**fswatch**](http://emcrisostomo.github.io/fswatch/) 。
@ -138,14 +159,16 @@ $ bash tools/run.sh
|站点类型 | 仓库名称|
|:---|:---|
|User or Organization | `<username>.github.io`|
|Project| `<username>.github.io` 以外的名字, 譬如 `project`|
|Project| `<username>.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://<username>.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) 点击按钮 <kbd>Sponsor</kbd> 选择 *支付宝、微信* 链接 <https://cotes.gitee.io/alipay-wechat-donation> 即可完成,您的打赏将会鼓励作者去更好地完成开源项目!
如果您喜欢这个主题或者它对您有帮助,请考虑打赏作者:在 [项目主页](https://github.com/cotes2020/jekyll-theme-chirpy) 点击按钮 <kbd>:heart:Sponsor</kbd> 选择适合的链接即可完成(国内一般选第二个链接,支付宝/微信赞助),您的打赏将会极大地鼓励作者,并帮助作者更好地维护项目!
## License 许可
## 许可证书
本项目开源,基于 [MIT](https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/LICENSE) 许可。