Skip to content

Commit 52301ed

Browse files
cotes2020cotes2020
committed
Updated README and tutorial.
Formatted README.
1 parent 26c7dfd commit 52301ed

File tree

5 files changed

+181
-86
lines changed

5 files changed

+181
-86
lines changed

‎.github/CONTRIBUTING.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# How to Contribute
2+
3+
I want to thank you for sparing a time to improve this project! Here are some guidelines for contributing：
4+
5+
## Bug Reporting
6+
7+
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.
8+
9+
10+
## Code Optimization
11+
12+
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.
13+
14+
15+
## Feature Request
16+
17+
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.
18+
19+
20+
---
21+
22+
:tada:Your volunteering will make the open source world more beautiful, thanks again!:tada:

‎README.md‎

Lines changed: 74 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -4,51 +4,84 @@
44
[![GitHub license](https://img.shields.io/github/license/cotes2020/jekyll-theme-chirpy.svg)](https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/LICENSE)
55
[![996.icu](https://img.shields.io/badge/link-996.icu-%23FF4D5B.svg)](https://996.icu)
66

7-
English | [中文](README_zh-CN.md)
8-
9-
![devices-mockup](https://raw.githubusercontent.com/cotes2020/jekyll-theme-chirpy/master/assets/img/sample/devices-mockup.png)
10-
11-
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)
7+
Language: English | [简体中文](docs/README_zh-CN.md)
128

9+
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.
1310

14-
## Features
11+
You will get the following features:
1512

1613
* Auto Dark Mode
1714
* Posts' Last Modified Date
1815
* Table of Contents
19-
* Recommand Related Post Automatically
20-
* Disqus Comments
16+
* Automatically Recommend Related Posts
2117
* Syntax highlighting
2218
* Two Level Categories
2319
* Search
24-
* HTML Compress
2520
* Atom Feeds
21+
* Disqus Comments
2622
* Google Analytics
2723
* GA Pageviews (Advanced)
2824
* SEO Tag
2925
* Performance Optimization
3026

31-
## Quick Start
27+
[**Live Demo** »](https://chirpy.cotes.info)
28+
29+
![devices-mockup](https://raw.githubusercontent.com/cotes2020/jekyll-theme-chirpy/master/assets/img/sample/devices-mockup.png)
30+
31+
## Table of Contents
32+
33+
* [Getting Started](#getting-started)
34+
* [Usage](#usage)
35+
* [Contributing](#contributing)
36+
* [Credits](#credits)
37+
* [Support](#support)
38+
* [License](#license)
39+
3240

33-
### Preparation
41+
## Getting Started
3442

35-
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/).
43+
### Prerequisites
3644

37-
Next, [fork](https://github.com/cotes2020/jekyll-theme-chirpy/fork) **Chirpy** and then clone your forked repo locally.
45+
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/).
3846

47+
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:
3948

40-
### Install Jekyll Plugins
49+
* Debian
4150

42-
Go to the root of repo and run:
51+
```console
52+
$ sudo apt-get install coreutils
53+
```
54+
55+
* macOS
56+
57+
```console
58+
$ brew install coreutils
59+
```
60+
61+
62+
### Installing
63+
64+
[Fork **Chirpy** from GitHub](https://github.com/cotes2020/jekyll-theme-chirpy/fork), then clone your forked repo to local:
65+
66+
```console
67+
$ git clone git@github.com:USER/jekyll-theme-chirpy.git
68+
```
69+
70+
replace the `USER` above to your GitHub username.
71+
72+
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:
4373

4474
```terminal
4575
$ bundle install
4676
```
4777

48-
`bundle` will install all the dependent Jekyll Plugins listed in file `Gemfile` automatically.
78+
`bundle` will automatically install all the dependent Jekyll Plugins that listed in the `Gemfile`.
79+
4980

81+
## Usage
5082

51-
### File Structure
83+
84+
### Directory Structure
5285

5386
The main files and related brief introductions are listed below.
5487

@@ -72,6 +105,7 @@ jekyll-theme-chirpy/
72105
├── README.md
73106
├── _config.yml # configuration file
74107
├── tools # script tools
108+
├── docs
75109
├── feed.xml
76110
├── index.html
77111
├── robots.txt
@@ -86,28 +120,18 @@ As mentioned above, some files or directories should be removed from your repo:
86120
- _scripts/travis
87121

88122

89-
### Configuration
123+
### Customization
90124

91-
Customize the variables in file `_config.yml` as needed.
125+
Basically, go to `_config.yml` and customize the variables as needed, some of them are typical options:
92126

93127
* Avatar
94128

95-
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).
129+
`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).
96130

97131
* TimeZone
98132

99133
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).
100134

101-
* Atom Feed
102-
103-
The Atom feed url of your site will be:
104-
105-
```
106-
<SITE_URL>/feed.xml
107-
```
108-
109-
The `SITE_URL` was defined by variable `url` of `_config.yml`.
110-
111135

112136
### Run Locally
113137

@@ -117,11 +141,9 @@ You may want to preview the site before publishing, so just run the script tool:
117141
$ bash tools/run.sh
118142
```
119143

120-
>**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.
144+
Open a modern brower and visit at <http://localhost:4000>.
121145

122-
Open a brower and visit <http://localhost:4000>.
123-
124-
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.
146+
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.
125147

126148
### Deploying to GitHub Pages
127149

@@ -142,10 +164,12 @@ By deploying the site in this way, you're allowed to push the source code direct
142164

143165
**2**. Commit the changes of the repo first, then run the initialization script:
144166

145-
```console
167+
```terminal
146168
$ bash tools/init.sh
147169
```
148170

171+
>**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.
172+
149173
it will automatically generates the *Latest Modified Date* and *Categories / Tags* page for the posts.
150174

151175
**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
192216

193217
and enjoy!
194218

219+
### Documentation
220+
221+
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).
222+
223+
## Contributing
224+
225+
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).
226+
227+
228+
## Credits
195229

196-
## Documentation
230+
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).
197231

198-
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).
232+
: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.
199233

200-
## Sponsor
201234

202-
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.
235+
## Support
203236

237+
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.
204238

205239

206240
## License
207241

208-
This work is published under [MIT](https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/LICENSE) License.
242+
This work is published under [MIT](https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/LICENSE) License.

‎_config.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -168,6 +168,7 @@ exclude:
168168
- Gemfile.lock
169169
- Gemfile
170170
- tools
171+
- docs
171172

172173
sitemap_exclude: # Sitemap will exclude the following items.
173174
fuzzy:

‎_posts/2019-08-09-getting-started.md‎

Lines changed: 16 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,21 @@ tags: [getting started]
77

88
## Preparation
99

10-
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/).
10+
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/).
1111

12-
Next, [fork](https://github.com/cotes2020/jekyll-theme-chirpy/fork) **Chirpy** and then clone your forked repo locally.
12+
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:
13+
14+
* Debian
15+
16+
```console
17+
$ sudo apt-get install coreutils
18+
```
19+
20+
* macOS
21+
22+
```console
23+
$ brew install coreutils
24+
```
1325

1426

1527
## Install Jekyll Plugins
@@ -73,16 +85,6 @@ Customize the variables in file `_config.yml` as needed.
7385

7486
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).
7587

76-
* Atom Feed
77-
78-
The Atom feed url of your site will be:
79-
80-
```
81-
<SITE_URL>/feed.xml
82-
```
83-
84-
The `SITE_URL` was defined by variable `url` of `_config.yml`.
85-
8688

8789
## Run Locally
8890

@@ -92,8 +94,6 @@ You may want to preview the site before publishing, so just run the script tool:
9294
$ bash tools/run.sh
9395
```
9496

95-
>**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.
96-
9797
Open a brower and visit <http://localhost:4000>.
9898

9999
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
122122
$ bash tools/init.sh
123123
```
124124

125+
> 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.
126+
125127
it will automatically generates the *Latest Modified Date* and *Categories / Tags* page for the posts.
126128

127129
**3**. Push the changes to `origin/master` then go to GitHub website and enable GitHub Pages service for the repo.

0 commit comments

Comments
 (0)