Skip to content

Commit 6275196

Browse files
cotes2020cotes2020
committed
Merge branch 'release/2.5'
2 parents c0e7521 + 3e118de commit 6275196

18 files changed

+482
-464
lines changed

‎.github/workflows/pages-deploy.yml.hook

+99
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
name: 'Automatic build'
2+
on:
3+
push:
4+
branches:
5+
- master
6+
paths-ignore:
7+
- '.gitignore'
8+
- 'README.md'
9+
- 'LICENSE'
10+
11+
jobs:
12+
build-n-test:
13+
runs-on: ubuntu-latest
14+
15+
steps:
16+
- uses: actions/setup-ruby@v1
17+
with:
18+
ruby-version: '2.6.x'
19+
20+
- name: Checkout
21+
uses: actions/checkout@v2
22+
with:
23+
fetch-depth: 0
24+
25+
- name: Bundle Caching
26+
id: bundle-cache
27+
uses: actions/cache@v1
28+
with:
29+
path: vendor/bundle
30+
key: ${{ runner.os }}-gems-${{ hashFiles('**/Gemfile') }}
31+
restore-keys: |
32+
${{ runner.os }}-gems-
33+
34+
- name: Bundle config
35+
run: |
36+
bundle config path vendor/bundle
37+
38+
- name: Bundle Install
39+
if: steps.bundle-cache.outputs.cache-hit != 'true'
40+
run: |
41+
bundle install
42+
43+
- name: Bundle Install locally
44+
if: steps.bundle-cache.outputs.cache-hit == 'true'
45+
run: |
46+
bundle install --local
47+
48+
- name: Build Site
49+
run: |
50+
bash tools/build.sh -b ""
51+
52+
- name: Test Site
53+
run: |
54+
bash tools/test.sh
55+
56+
deploy:
57+
needs: build-n-test
58+
runs-on: ubuntu-latest
59+
60+
steps:
61+
- uses: actions/setup-ruby@v1
62+
with:
63+
ruby-version: '2.6.x'
64+
65+
- name: Checkout
66+
uses: actions/checkout@v2
67+
with:
68+
fetch-depth: 0
69+
70+
- name: Bundle Caching
71+
id: bundle-cache
72+
uses: actions/cache@v1
73+
with:
74+
path: vendor/bundle
75+
key: ${{ runner.os }}-gems-${{ hashFiles('**/Gemfile') }}
76+
restore-keys: |
77+
${{ runner.os }}-gems-
78+
79+
- name: Bundle config
80+
run: |
81+
bundle config path vendor/bundle
82+
83+
- name: Bundle Install
84+
if: steps.bundle-cache.outputs.cache-hit != 'true'
85+
run: |
86+
bundle install
87+
88+
- name: Bundle Install locally
89+
if: steps.bundle-cache.outputs.cache-hit == 'true'
90+
run: |
91+
bundle install --local
92+
93+
- name: Build site
94+
run: |
95+
bash tools/build.sh
96+
97+
- name: Deploy
98+
run: |
99+
bash tools/deploy.sh

‎README.md

+65-130
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ A minimal, sidebar, responsive web design Jekyll theme, focusing on text present
1313
## Table of Contents
1414

1515
* [Features](#features)
16-
* [Installing](#installing)
16+
* [Installation](#installation)
1717
* [Usage](#usage)
1818
* [Contributing](#contributing)
1919
* [Credits](#credits)
@@ -37,13 +37,28 @@ A minimal, sidebar, responsive web design Jekyll theme, focusing on text present
3737
* GA Pageviews reporting (Advanced)
3838
* SEO and Performance Optimization
3939

40-
## Installing
4140

42-
### Prerequisites
41+
## Installation
4342

44-
Follow the [Jekyll Docs](https://jekyllrb.com/docs/installation/) to complete the installation of basic environment (`Ruby`, `RubyGems` and `Bundler`).
43+
[Fork **Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/fork) on GitHub, and clone the fork to local by:
4544

46-
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:
45+
```terminal
46+
$ git clone git@github.com:<username>/jekyll-theme-chirpy -b master --single-branch
47+
```
48+
49+
### Setting up the local envrionment
50+
51+
If you would like to run or build the project on your local machine, please follow the [Jekyll Docs](https://jekyllrb.com/docs/installation/) to complete the installation of `Ruby`, `RubyGems` and `Bundler`.
52+
53+
Before running or building for the first time, please complete the installation of the Jekyll plugins. Go to the root directory of project and run:
54+
55+
```terminal
56+
$ bundle install
57+
```
58+
59+
`bundle` will automatically install all the dependencies specified by `Gemfile`.
60+
61+
What's more, in order to generate some extra files (*categories*, *tags* and *last modified list*), we need to use some tool scripts. If your machine is running Debian or macOS, make sure that [GNU coreutils](https://www.gnu.org/software/coreutils/) is installed. Otherwise, install by:
4762

4863
* Debian
4964

@@ -58,131 +73,84 @@ To improve the writing experience, we need to use some script tools. If your mac
5873
```
5974

6075

61-
### Jekyll Plugins
76+
## Usage
6277

63-
[Fork **Chirpy** from GitHub](https://github.com/cotes2020/jekyll-theme-chirpy/fork), then clone your forked repo to local:
78+
Running [**Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/) requires some extra files, which cannot be generated by Jekyll native commands, so please strictly follow the methods mentioned below to run or deploy your website.
6479

65-
```console
66-
$ git clone git@github.com:USER/jekyll-theme-chirpy.git -b master
67-
```
68-
69-
And replace the `USER` above to your GitHub username.
80+
### Initialization
7081

71-
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:
82+
Go to the root directory of the project and start initialization:
7283

73-
```terminal
74-
$ bundle install
84+
```console
85+
$ bash tools/init.sh
7586
```
7687

77-
`bundle` will automatically install all the dependent Jekyll Plugins that listed in the `Gemfile`.
78-
79-
80-
## Usage
81-
82-
83-
### Directory Structure
84-
85-
The main files and related brief introductions are listed below:
86-
87-
```sh
88-
jekyll-theme-chirpy/
89-
├── _data
90-
├── _includes
91-
├── _layouts
92-
├── _posts # posts stay here
93-
├── _scripts
94-
├── .travis.yml # remove it
95-
├── .github # remove this, too
96-
├── assets
97-
├── tabs
98-
│   └── about.md # the ABOUT page
99-
├── .gitignore
100-
├── 404.html
101-
├── Gemfile
102-
├── LICENSE
103-
├── README.md
104-
├── _config.yml # configuration file
105-
├── tools # script tools
106-
├── docs
107-
├── feed.xml
108-
├── index.html
109-
├── robots.txt
110-
└── sitemap.xml
111-
```
88+
> If you not intend to deploy it on GitHub Pages, append parameter option `--no-gh` at the end of the above command.
11289
90+
What it does is:
11391

114-
As mentioned above, some files or directories should be removed from your repo:
92+
1. Remove some files or directories from your repository:
93+
- `.travis.yml`
94+
- everything under `.github/`
95+
- files under `_posts/`
96+
- folder `docs/`
11597

116-
```terminal
117-
$ rm -rf .travis.yml .github _posts/*
118-
```
98+
2. Unless the option `--no-gh` was enabled, setup the GitHub action workflow by renaming `pages-deploy.yml.hook` of directory `.github/workflows/` to `pages-deploy.yml`.
11999

100+
3. Automatically create a commit to save the changes.
120101

121102
### Configuration
122103

123104
Generally, go to `_config.yml` and configure the variables as needed. Some of them are typical options:
124-
125105
* `url`
126-
127-
Set to your website url and there should be no slash symbol at the tail. Format: `<protocol>://<domain>`.
128-
129-
130106
* `avatar`
131-
132-
It defines the image file location of avatar. The sample image is `/assets/img/sample/avatar.jpg`, and should be replaced by your own one(a square image). Notice that a huge image file will increase the load time of your site, so keep your avatar image size as small as possible(may be *<https://tinypng.com/>* will help).
133-
134107
* `timezone`
135-
136-
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).
137-
138108
* `theme_mode`
139-
140-
There are three options for the theme color scheme:
141-
142-
- **dual** - The default color scheme will follow the system settings, but if the system does not support dark mode, or the browser does not support `Media Queries Level 5`, the theme will be displayed as `light` mode by default. Anyway, the bottom left corner of the Sidebar will provide a button for users to switch color schemes.
143109

144-
- **dark** - Always show dark mode.
145-
- **light** - Always show light mode.
146110

111+
### Run Locally
147112

148-
### Run Locally
149-
150-
You may want to preview the site content before publishing, so just run the script tool:
113+
You may want to preview the site contents before publishing, so just run it by:
151114

152115
```terminal
153116
$ bash tools/run.sh
154117
```
155118

156-
Open a modern browser and visit at <http://localhost:4000>.
119+
Then open a browser and visit to <http://localhost:4000>.
120+
121+
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+
123+
### Deployment
157124

158-
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.
125+
Before the deployment begins, checkout the file `_config.yml` and make sure the `url` is configured correctly. Furthermore, if you prefer the [_project site_](https://help.github.com/en/github/working-with-github-pages/about-github-pages#types-of-github-pages-sites) and don't use a custom domain, or you want to visit your website with a base url on a web server other than **GitHub Pages**, remember to change the `baseurl` to your project name that starting with a slash. For example, `/project`.
159126

160-
### Deploying to GitHub Pages
127+
Assuming you have already gone through the [initialization](#initialization), you can now choose any of the following methods to deploy your website.
161128

162-
Before the deployment begins, checkout the file `_config.yml` and make sure that the `url` has been configured. What's more, if you prefer the [Project site on GitHub](https://help.github.com/en/github/working-with-github-pages/about-github-pages#types-of-github-pages-sites) and also use the default domain `<username>.github.io`, remember to change the `baseurl` to your project name that starting with a slash. For example, `/project`.
129+
#### Deploy on GitHub Pages
163130

164-
#### Option 1: Built by GitHub Pages
131+
For security reasons, GitHub Pages build runs on `safe` mode, which restricts us from using tool scripts to generate additional page files. Therefore, we can use GitHub Actions to build the site, store the built site files on a new branch, and use that branch as the source of the Pages service.
165132

166-
By deploying the site in this way, you're allowed to push the source code directly to the remote.
133+
1. Push any commit to `origin/master` to trigger the GitHub Actions workflow. Once the build is complete, a new remote branch called `gh-pages` will appear, which is used to store the built site files.
167134

168-
> **Note**: If you want to use any third-party Jekyll plugins that not on [this list](https://pages.github.com/versions/), stop reading the current approach and go to [*Option 2: Build locally*](#option-2-build-locally).
135+
2. Unless you prefer to project sites, rename your repository to `<username>.github.io` on GitHub.
169136

170-
**1**. Rename the repository to:
137+
3. Choose branch `gh-pages` as your GitHub Pages source.
171138

172-
|Site Type | Repo's Name|
173-
|:---|:---|
174-
|User or Organization | `<username>.github.io`|
175-
|Project| Any one except `<username>.github.io`, let's say `project`|
139+
4. Visit your website at the address indicated by GitHub.
176140

177-
**2**. Commit the changes of the repo first, then run the publish script:
141+
#### Deploy on Other Platforms
142+
143+
On platforms other than GitHub, e.g. GitLab, we cannot enjoy the convenience of **GitHub Actions**. However, we have a tool to make up for this shortcoming.
144+
145+
Commit the changes of your repository first, then run the publish script:
178146

179147
```console
180148
$ bash tools/publish.sh
181149
```
182150

183151
> 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.
184152
185-
it will automatically generates the *Latest Modified Date* and *Categories / Tags* page for the posts and submit a commit, and then push to `origin/master`. Its output is similar to the following log:
153+
It will automatically generates the *Latest Modified Date* and *Categories / Tags* page for the posts and submit a commit, then push to `origin/master`. Its output is similar to the following log:
186154

187155
```terminal
188156
[INFO] Success to update lastmod for 4 post(s).
@@ -191,54 +159,21 @@ it will automatically generates the *Latest Modified Date* and *Categories / Tag
191159
[INFO] Published successfully!
192160
```
193161

194-
**3**. Go to GitHub website and enable GitHub Pages service for the repo.
195-
196-
**4**. Check it out:
162+
Lastly, enable the pages service according to the instructions of the platform you choose.
197163

198-
|Site Type | Site URL |
199-
|:---|:---|
200-
|User or Organization | `https://<username>.github.io/`|
201-
|Project| `https://<username>.github.io/project/`|
164+
#### Deploy on Private Server
202165

203-
204-
#### Option 2: Build Locally
205-
206-
For security reasons, GitHub Pages runs on `safe` mode, which means the third-party Jekyll plugins or custom scripts won't work. If you want to use any other plugin that not on the [whitelist](https://pages.github.com/versions/), **you have to generate the site locally rather than on GitHub Pages**.
207-
208-
**1**. Browse to GitHub website, create a brand new repo named:
209-
210-
|Site Type | Repo's Name|
211-
|:---|:---|
212-
|User or Organization | `<username>.github.io`|
213-
|Project| Any one except `<username>.github.io`, let's say `project`|
214-
215-
and clone it.
216-
217-
**2**. In the root of the source project, build your site by:
166+
In the root of the source project, build your site by:
218167

219168
```console
220-
$ bash tools/build.sh -d /path/to/local/project/
169+
$ bash tools/build.sh -d /path/to/site/
221170
```
222171

223-
The generated static files will be placed in the root of `/path/to/local/project`. Commit and push the changes to the `master` branch on GitHub.
224-
225-
**3**. Go to GitHub website and enable Pages service for the new repository.
226-
227-
**4**. Visit at:
228-
229-
|Site Type | Site URL |
230-
|:---|:---|
231-
|User or Organization | `https://<username>.github.io/`|
232-
|Project| `https://<username>.github.io/project/`|
233-
234-
#### Finishing work
235-
236-
No matter which way you choose to deploy the website on GitHub, please enforce the `HTTPS` for it. See official docs: [Securing your GitHub Pages site with HTTPS](https://help.github.com/en/github/working-with-github-pages/securing-your-github-pages-site-with-https).
237-
172+
The generated site files will be placed in the root of `/path/to/site/`. Now you should upload those files to your web server, such as Nginx.
238173

239174
### Documentation
240175

241-
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).
176+
For more details and the better reading experience, please check out the [tutorials on 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).
242177

243178
## Contributing
244179

@@ -247,14 +182,14 @@ The old saying, "Two heads are better than one." Consequently, welcome to report
247182

248183
## Credits
249184

250-
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).
185+
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).
251186

252-
:tada:Thanks to all the volunteers who contributed to this project, their GitHub IDs are on [this list](https://github.com/cotes2020/jekyll-theme-chirpy/graphs/contributors). Also, I won't forget those guys who submitted the issues or unmerged PR because they reported bugs, shared ideas or inspired me to write more readable documentation.
187+
:tada: Thanks to all the volunteers who contributed to this project, their GitHub IDs are on [this list](https://github.com/cotes2020/jekyll-theme-chirpy/graphs/contributors). Also, I won't forget those guys who submitted the issues or unmerged PR because they reported bugs, shared ideas or inspired me to write more readable documentation.
253188

254189

255190
## Support
256191

257-
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 and help me better maintain the project.
192+
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 and help me better maintain the project.
258193

259194

260195
## License

0 commit comments

Comments
 (0)