From b0d6513b7c7195e084e7f7923bb39b58353cb81d Mon Sep 17 00:00:00 2001 From: Cotes Chung <11371340+cotes2020@users.noreply.github.com> Date: Thu, 9 Jan 2020 20:24:44 +0800 Subject: [PATCH] Updated README and tutorial. Formatted README. --- .github/CONTRIBUTING.md | 22 +++++ README.md | 114 +++++++++++++++--------- _config.yml | 1 + _posts/2019-08-09-getting-started.md | 30 ++++--- README_zh-CN.md => docs/README_zh-CN.md | 100 ++++++++++++++------- 5 files changed, 181 insertions(+), 86 deletions(-) create mode 100644 .github/CONTRIBUTING.md rename README_zh-CN.md => docs/README_zh-CN.md (60%) 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) 许可。