Update the usage instructions

This commit is contained in:
Cotes Chung 2021-01-25 20:19:50 +08:00
parent b85980e1e2
commit 4343f1a8f8
3 changed files with 242 additions and 133 deletions

129
README.md
View file

@ -1,6 +1,6 @@
# Chirpy # Chirpy
Language: English | [简体中文](docs/README.zh-CN.md) Language: English | [简体中文](https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/docs/README.zh-CN.md)
[![Build Status](https://github.com/cotes2020/jekyll-theme-chirpy/workflows/build/badge.svg?branch=master&event=push)](https://github.com/cotes2020/jekyll-theme-chirpy/actions?query=branch%3Amaster+event%3Apush) [![Build Status](https://github.com/cotes2020/jekyll-theme-chirpy/workflows/build/badge.svg?branch=master&event=push)](https://github.com/cotes2020/jekyll-theme-chirpy/actions?query=branch%3Amaster+event%3Apush)
[![Codacy Badge](https://api.codacy.com/project/badge/Grade/8220b926db514f13afc3f02b7f884f4b)](https://app.codacy.com/manual/cotes2020/jekyll-theme-chirpy?utm_source=github.com&utm_medium=referral&utm_content=cotes2020/jekyll-theme-chirpy&utm_campaign=Badge_Grade_Dashboard) [![Codacy Badge](https://api.codacy.com/project/badge/Grade/8220b926db514f13afc3f02b7f884f4b)](https://app.codacy.com/manual/cotes2020/jekyll-theme-chirpy?utm_source=github.com&utm_medium=referral&utm_content=cotes2020/jekyll-theme-chirpy&utm_campaign=Badge_Grade_Dashboard)
@ -15,6 +15,7 @@ A minimal, sidebar, responsive web design Jekyll theme that focuses on text pres
- [Features](#features) - [Features](#features)
- [Installation](#installation) - [Installation](#installation)
- [Prerequisites](#prerequisites)
- [Usage](#usage) - [Usage](#usage)
- [Contributing](#contributing) - [Contributing](#contributing)
- [Credits](#credits) - [Credits](#credits)
@ -39,80 +40,102 @@ A minimal, sidebar, responsive web design Jekyll theme that focuses on text pres
- GA Pageviews reporting (Advanced) - GA Pageviews reporting (Advanced)
- SEO and Performance Optimization - SEO and Performance Optimization
## Prerequisites
Follow the [Jekyll Docs](https://jekyllrb.com/docs/installation/) to complete the installation of `Ruby`, `RubyGems`, `Jekyll` and `Bundler`.
## Installation ## Installation
[Fork **Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/fork) on GitHub, rename the repository to `USERNAME.github.io` (where `USERNAME` is your GitHub username), and then open terminal and clone the fork to local by: There are two ways to get the theme:
```terminal - Install from [RubyGems](https://rubygems.org/gems/jekyll-theme-chirpy)
$ git clone https://github.com/USERNAME/USERNAME.github.io.git -b master --single-branch - Fork from GitHub
### Install From Rubygems
Add this line to your Jekyll site's `Gemfile`:
```ruby
gem "jekyll-theme-chirpy"
``` ```
### Setting up the local envrionment And add this line to your Jekyll site's `_config.yml`:
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`, `Jekyll` and `Bundler`. ```yaml
theme: jekyll-theme-chirpy
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:
```terminal
$ bundle install
``` ```
`bundle` will automatically install all the dependencies specified by `Gemfile`. And then execute:
### Setting up Docker environment (optional)
If you're a loyal fan of [**Docker**](https://www.docker.com/) or just too lazy to install the packages mentioned in [_Setting up the local envrionment_](#setting-up-the-local-envrionment), please make sure you have **Docker Engine** installed and running, and then get Docker image `jekyll/jekyll` from Docker Hub by the following command:
```console ```console
$ docker pull jekyll/jekyll $ bundle
``` ```
## Usage Finally, copy the missing files (refer to the [starter project][starter] for the detailed file directory structure) from the theme's gem to your Jekyll site, and append all the variables of the theme's `_config.yml` to your Jekyll site.
### Initialization > **Hint**: To locate the themes gem, execute:
>
```console
$ bundle info --path jekyll-theme-chirpy
```
Go to the root directory of the project and start initialization: Or you can [use the starter template][use-starter] to create a Jekyll site to save time copying contents from theme's gem.
[starter]: https://github.com/cotes2020/chirpy-starter
[use-starter]: https://github.com/cotes2020/chirpy-starter/generate
### Fork From GitHub
[Fork **Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/fork) from GitHub and clone your fork to local.
Install gem dependencies by:
```console
$ bundle
```
And then execute:
```console ```console
$ bash tools/init.sh $ bash tools/init.sh
``` ```
> **Note**: If you not intend to deploy it on GitHub Pages, append parameter option `--no-gh` at the end of the above command. > **Note**: If you don't plan to deploy your site on GitHub Pages, append parameter option `--no-gh` at the end of the above command.
What it does is: What it does is:
1. Remove some files or directories from your repository: 1. Remove some files or directories from your repository:
- `.travis.yml` - `.travis.yml`
- files under `_posts` - files under `_posts`
- folder `docs` - folder `docs`
2. If you use the `--no-gh` option, the directory `.github` will be deleted. Otherwise, setup the GitHub Action workflow by removing extension `.hook` of `.github/workflows/pages-deploy.yml.hook`, and then remove the other files and directories in folder `.github`. 2. If you use the `--no-gh` option, the directory `.github` will be deleted. Otherwise, setup the GitHub Action workflow by removing extension `.hook` of `.github/workflows/pages-deploy.yml.hook`, and then remove the other files and directories in folder `.github`.
3. Automatically create a commit to save the changes. 3. Automatically create a commit to save the changes.
## Usage
### Configuration ### Configuration
Generally, go to `_config.yml` and configure the variables as needed. Some of them are typical options: Update the variables of `_config.yml` as needed. Some of them are typical options:
- `url` - `url`
- `avatar` - `avatar`
- `timezone` - `timezone`
- `theme_mode` - `theme_mode`
### Run Locally ### Running Local Server
You may want to preview the site contents before publishing, so just run it by: You may want to preview the site contents before publishing, so just run it by:
```terminal ```console
$ bundle exec jekyll s $ bundle exec jekyll s
``` ```
Then open a browser and visit to <http://localhost:4000>. Or run the site on Docker with the following command:
### Run on Docker
Run the site on Docker with the following command:
```terminal ```terminal
$ docker run -it --rm \ $ docker run -it --rm \
@ -121,22 +144,34 @@ $ docker run -it --rm \
jekyll serve jekyll serve
``` ```
Open a browser and visit to _<http://localhost:4000>_.
### Deployment ### Deployment
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`. 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, e.g, `/project-name`.
Assuming you have already gone through the [initialization](#initialization), you can now choose ONE of the following methods to deploy your website. Now you can now choose ONE of the following methods to deploy your website.
#### Deploy on GitHub Pages #### Deploy on GitHub Pages
For security reasons, GitHub Pages build runs on `safe` mode, which restricts us from using plugins 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. For security reasons, GitHub Pages build runs on `safe` mode, which restricts us from using plugins 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 GH Pages service.
1. Push any commit to `origin/master` to trigger the GitHub Actions workflow. Once the build is complete and successful, a new remote branch named `gh-pages` will appear to store the built site files. Ensure your Jekyll site has the file `/.github/workflows/pages-deploy.yml`.
Otherwise, create a new one and fill in the contents of the [workflow file][workflow], and the value of the `on.push.branches` should be the same as your repo's default branch name.
[workflow]:https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/.github/workflows/pages-deploy.yml.hook
Rename your repoistory to `<GH-USERNAME>.github.io` on GitHub.
And then publish your site by:
1. Push any commit to remote to trigger the GitHub Actions workflow. Once the build is complete and successful, a new remote branch named `gh-pages` will appear to store the built site files.
2. Browse to your repo's landing page on GitHub and select the branch `gh-pages` as the [publishing source](https://docs.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site) throught _Settings__Options__GitHub Pages_:
2. Browse to your repo's landing page on GitHub and select the branch `gh-pages` as the [publishing source](https://docs.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site) throught _Settings__Options__GitHub Pages_:
![gh-pages-sources](https://cdn.jsdelivr.net/gh/cotes2020/chirpy-images/posts/20190809/gh-pages-sources.png) ![gh-pages-sources](https://cdn.jsdelivr.net/gh/cotes2020/chirpy-images/posts/20190809/gh-pages-sources.png)
3. Visit your website at the address indicated by GitHub. 3. Visit your website at the address indicated by GitHub.
#### Deploy on Other Platforms #### Deploy on Other Platforms
@ -148,7 +183,7 @@ Go to the root of the source project, build your site by:
$ JEKYLL_ENV=production bundle exec jekyll b $ JEKYLL_ENV=production bundle exec jekyll b
``` ```
Or, build the site with Docker by: Or build the site with Docker by:
```terminal ```terminal
$ docker run -it --rm \ $ docker run -it --rm \
@ -160,7 +195,7 @@ $ docker run -it --rm \
Unless you specified the output path, the generated site files will be placed in folder `_site` of the project's root directory. Now you should upload those files to your web server. Unless you specified the output path, the generated site files will be placed in folder `_site` of the project's root directory. Now you should upload those files to your web server.
### Documentation ## Documentation
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). 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).
@ -174,6 +209,12 @@ This theme is mainly built with [Jekyll](https://jekyllrb.com/) ecosystem, [Boot
: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. :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.
Also, thank [JetBrains][JB] for providing the open source license.
[![JB-logo](https://cdn.jsdelivr.net/gh/cotes2020/chirpy-images/commons/jetbrains.svg)][JB]
[JB]:https://www.jetbrains.com/?from=jekyll-theme-chirpy
## Supporting ## Supporting
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. 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.

View file

@ -7,105 +7,137 @@ tags: [getting started]
pin: true pin: true
--- ---
## Prerequisites
Follow the [Jekyll Docs](https://jekyllrb.com/docs/installation/) to complete the installation of `Ruby`, `RubyGems`, `Jekyll` and `Bundler`.
## Installation ## Installation
[Fork **Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/fork) on GitHub, rename the repository to `USERNAME.github.io` (where `USERNAME` is your GitHub username), and then open terminal and clone the fork to local by: There are two ways to get the theme:
```terminal - Install from [RubyGems](https://rubygems.org/gems/jekyll-theme-chirpy)
$ git clone https://github.com/USERNAME/USERNAME.github.io.git -b master --single-branch - Fork from GitHub
### Install From Rubygems
Add this line to your Jekyll site's `Gemfile`:
```ruby
gem "jekyll-theme-chirpy"
``` ```
### Setting up the local envrionment And add this line to your Jekyll site's `_config.yml`:
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`, `Jekyll` and `Bundler`. ```yaml
theme: jekyll-theme-chirpy
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:
```terminal
$ bundle install
``` ```
`bundle` will automatically install all the dependencies specified by `Gemfile`. And then execute:
### Setting up Docker environment (optional)
If you're a loyal fan of [**Docker**](https://www.docker.com/) or just too lazy to install the packages mentioned in [_Setting up the local envrionment_](#setting-up-the-local-envrionment), please make sure you have **Docker Engine** installed and running, and then get Docker image `jekyll/jekyll` from Docker Hub by the following command:
```console ```console
$ docker pull jekyll/jekyll $ bundle
``` ```
## Usage Finally, copy the missing files (refer to the [starter project][starter] for the detailed file directory structure) from the theme's gem to your Jekyll site, and append all the variables of the theme's `_config.yml` to your Jekyll site.
### Initialization > **Hint**: To locate the themes gem, execute:
>
```console
$ bundle info --path jekyll-theme-chirpy
```
Go to the root directory of the project and start initialization: Or you can [use the starter template][use-starter] to create a Jekyll site to save time copying contents from theme's gem.
[starter]: https://github.com/cotes2020/chirpy-starter
[use-starter]: https://github.com/cotes2020/chirpy-starter/generate
### Fork From GitHub
[Fork **Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/fork) from GitHub and clone your fork to local.
Install gem dependencies by:
```console
$ bundle
```
And then execute:
```console ```console
$ bash tools/init.sh $ bash tools/init.sh
``` ```
> **Note**: If you not intend to deploy it on GitHub Pages, append parameter option `--no-gh` at the end of the above command. > **Note**: If you don't plan to deploy your site on GitHub Pages, append parameter option `--no-gh` at the end of the above command.
What it does is: What it does is:
1. Remove some files or directories from your repository: 1. Remove some files or directories from your repository:
- `.travis.yml` - `.travis.yml`
- files under `_posts` - files under `_posts`
- folder `docs` - folder `docs`
2. If you use the `--no-gh` option, the directory `.github` will be deleted. Otherwise, setup the GitHub Action workflow by removing extension `.hook` of `.github/workflows/pages-deploy.yml.hook`, and then remove the other files and directories in folder `.github`. 2. If you use the `--no-gh` option, the directory `.github` will be deleted. Otherwise, setup the GitHub Action workflow by removing extension `.hook` of `.github/workflows/pages-deploy.yml.hook`, and then remove the other files and directories in folder `.github`.
3. Automatically create a commit to save the changes. 3. Automatically create a commit to save the changes.
## Usage
### Configuration ### Configuration
Generally, go to `_config.yml` and configure the variables as needed. Some of them are typical options: Update the variables of `_config.yml` as needed. Some of them are typical options:
- `url` - `url`
- `avatar` - `avatar`
- `timezone` - `timezone`
- `theme_mode` - `theme_mode`
### Run Locally ### Running Local Server
You may want to preview the site contents before publishing, so just run it by: You may want to preview the site contents before publishing, so just run it by:
```terminal ```console
$ bundle exec jekyll s $ bundle exec jekyll s
``` ```
Then open a browser and visit to <http://localhost:4000>. Or run the site on Docker with the following command:
### Run on Docker
Run the site on Docker with the following command:
```terminal ```terminal
$ docker run --rm -it \ $ docker run -it --rm \
--volume="$PWD:/srv/jekyll" \ --volume="$PWD:/srv/jekyll" \
-p 4000:4000 jekyll/jekyll \ -p 4000:4000 jekyll/jekyll \
jekyll serve jekyll serve
``` ```
Open a browser and visit to _<http://localhost:4000>_.
### Deployment ### Deployment
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`. 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, e.g, `/project-name`.
Assuming you have already gone through the [initialization](#initialization), you can now choose ONE of the following methods to deploy your website. Now you can now choose ONE of the following methods to deploy your website.
#### Deploy on GitHub Pages #### Deploy on GitHub Pages
For security reasons, GitHub Pages build runs on `safe` mode, which restricts us from using plugins 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. For security reasons, GitHub Pages build runs on `safe` mode, which restricts us from using plugins 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 GH Pages service.
1. Push any commit to `origin/master` to trigger the GitHub Actions workflow. Once the build is complete and successful, a new remote branch named `gh-pages` will appear to store the built site files. Ensure your Jekyll site has the file `/.github/workflows/pages-deploy.yml`.
Otherwise, create a new one and fill in the contents of the [workflow file][workflow], and the value of the `on.push.branches` should be the same as your repo's default branch name.
2. Browse to your repo's landing page on GitHub and select the branch `gh-pages` as the [publishing source](https://docs.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site) throught _Settings__Options__GitHub Pages_: [workflow]:https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/.github/workflows/pages-deploy.yml.hook
![gh-pages-sources](https://cdn.jsdelivr.net/gh/cotes2020/chirpy-images/posts/20190809/gh-pages-sources.png){: width="650" class="normal"}
3. Visit your website at the address indicated by GitHub. Rename your repoistory to `<GH-USERNAME>.github.io` on GitHub.
And then publish your site by:
1. Push any commit to remote to trigger the GitHub Actions workflow. Once the build is complete and successful, a new remote branch named `gh-pages` will appear to store the built site files.
2. Browse to your repo's landing page on GitHub and select the branch `gh-pages` as the [publishing source](https://docs.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site) throught _Settings__Options__GitHub Pages_:
![gh-pages-sources](https://cdn.jsdelivr.net/gh/cotes2020/chirpy-images/posts/20190809/gh-pages-sources.png)
3. Visit your website at the address indicated by GitHub.
#### Deploy on Other Platforms #### Deploy on Other Platforms
@ -117,7 +149,7 @@ Go to the root of the source project, build your site by:
$ JEKYLL_ENV=production bundle exec jekyll b $ JEKYLL_ENV=production bundle exec jekyll b
``` ```
Or, build the site with Docker by: Or build the site with Docker by:
```terminal ```terminal
$ docker run -it --rm \ $ docker run -it --rm \

View file

@ -1,6 +1,6 @@
# Chirpy # Chirpy
Language: [English](../README.md) | 简体中文 Language: [English](https://github.com/cotes2020/jekyll-theme-chirpy#readme) | 简体中文
[![Build Status](https://github.com/cotes2020/jekyll-theme-chirpy/workflows/build/badge.svg?branch=master&event=push)](https://github.com/cotes2020/jekyll-theme-chirpy/actions?query=branch%3Amaster+event%3Apush) [![Build Status](https://github.com/cotes2020/jekyll-theme-chirpy/workflows/build/badge.svg?branch=master&event=push)](https://github.com/cotes2020/jekyll-theme-chirpy/actions?query=branch%3Amaster+event%3Apush)
[![Codacy Badge](https://api.codacy.com/project/badge/Grade/8220b926db514f13afc3f02b7f884f4b)](https://app.codacy.com/manual/cotes2020/jekyll-theme-chirpy?utm_source=github.com&utm_medium=referral&utm_content=cotes2020/jekyll-theme-chirpy&utm_campaign=Badge_Grade_Dashboard) [![Codacy Badge](https://api.codacy.com/project/badge/Grade/8220b926db514f13afc3f02b7f884f4b)](https://app.codacy.com/manual/cotes2020/jekyll-theme-chirpy?utm_source=github.com&utm_medium=referral&utm_content=cotes2020/jekyll-theme-chirpy&utm_campaign=Badge_Grade_Dashboard)
@ -16,6 +16,7 @@ Language: [English](../README.md) | 简体中文
## 目录 ## 目录
- [功能一览](#功能一览) - [功能一览](#功能一览)
- [前提要求](#前提要求)
- [安装](#安装) - [安装](#安装)
- [使用](#使用) - [使用](#使用)
- [参与贡献](#参与贡献) - [参与贡献](#参与贡献)
@ -42,40 +43,63 @@ Language: [English](../README.md) | 简体中文
- SEO 优化 - SEO 优化
- 网站性能优化 - 网站性能优化
## 前提要求
参考 [Jekyll Docs](https://jekyllrb.com/docs/installation/) 安装 `Ruby``RubyGems``Jekyll` 和 `Bundler`Docker 粉可免。
## 安装 ## 安装
[Fork **Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/fork),把仓库改名为 `USERNAME.github.io`(其中 `USERNAME` 是你的 GitHub 用户名), 然后克隆到本地: 有二法可得此主题:
```terminal - 从 [RubyGems](https://rubygems.org/gems/jekyll-theme-chirpy) 安装
$ git clone https://github.com/USERNAME/USERNAME.github.io.git -b master --single-branch - 从 GitHub 上 Fork
### Rubygems 安装
在你的 Jekyll 站点的 `Gemfile` 添加:
```ruby
gem "jekyll-theme-chirpy"
``` ```
### 设置本地环境 然后,添加这行到你的 Jekyll 站点的 `_config.yml`:
如果你想在本地运行或构建, 参考 [Jekyll Docs](https://jekyllrb.com/docs/installation/)安装 `Ruby``RubyGems``Jekyll` 和 `Bundler` ```yaml
theme: jekyll-theme-chirpy
首次运行或构建时, 请先安装 Jekyll plugins。在项目根目录运行
```terminal
$ bundle install
``` ```
`bundle` 会自动安装 `Gemfile` 内指定的依赖插件。 接着执行:
### 配置 Docker 镜像(可选)
如果你是 [**Docker**](https://www.docker.com/) 的铁粉,或者不想在本地安装上述 [_设置本地环境_](#设置本地环境) 提到的包, 那么请确保先安装并运行了 **Docker Engine** 然后从 Docker Hub 获取镜像 `jekyll/jekyll`:
```console ```console
$ docker pull jekyll/jekyll $ bundle
``` ```
最后, 拷贝额外所需主题的 gem 文件(详见 [starter 项目][starter] 的文件目录)至你的 Jekyll 站点, 然后把主题的 `_config.yml` 全部内容附加到你的 Jekyll 站点的同名文件。
## 使用 > **提示**: 定位主题的 gem 文件,可以执行:
>
```console
$ bundle info --path jekyll-theme-chirpy
```
### 初始化 或者你可以 [使用 starter template][use-starter] 来快速创建 Jekyll 站点,以省去复制主题 gem 文件的时间。
在项目根目录,开始初始化: [starter]: https://github.com/cotes2020/chirpy-starter
[use-starter]: https://github.com/cotes2020/chirpy-starter/generate
### 在 GitHub 上 Fork
[Fork **Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/fork) 然后克隆到本地。
安装依赖:
```console
$ bundle
```
接着执行文件初始化:
```console ```console
$ bash tools/init.sh $ bash tools/init.sh
@ -85,15 +109,17 @@ $ bash tools/init.sh
上述脚本完成了以下工作: 上述脚本完成了以下工作:
1. 从你的仓库中删除了: 1. 从你的仓库中删除了:
- `.travis.yml` - `.travis.yml`
- `_posts` 下的文件 - `_posts` 下的文件
- `docs` 目录 - `docs` 目录
2. 如果使用了参数 `--no-gh`,则会怒删 `.github`。否则,将会配置 GitHub Actions`.github/workflows/pages-deploy.yml.hook` 的后缀 `.hook` 去除,然后删除 `.github` 里的其他目录和文件。 2. 如果使用了参数 `--no-gh`,则会怒删 `.github`。否则,将会配置 GitHub Actions`.github/workflows/pages-deploy.yml.hook` 的后缀 `.hook` 去除,然后删除 `.github` 里的其他目录和文件。
3. 自动提交一个 Commit 以保存上述文件的更改。 3. 自动提交一个 Commit 以保存上述文件的更改。
## 使用
### 配置文件 ### 配置文件
@ -112,11 +138,7 @@ $ bash tools/init.sh
$ bundle exec jekyll s $ bundle exec jekyll s
``` ```
访问本地服务: <http://localhost:4000> 或者用 Docker 运行:
### 用 Docker 运行
在项目根目录运行命令:
```terminal ```terminal
$ docker run -it --rm \ $ docker run -it --rm \
@ -125,23 +147,31 @@ $ docker run -it --rm \
jekyll serve jekyll serve
``` ```
访问本地服务:<http://localhost:4000>
### 部署 ### 部署
部署开始前,把 `_config.yml``url` 改为 `https://<username>.github.io`(或者你的私有域名,如:`https://yourdomain.com`)。另外,如果你想使用 [Project 类型网站](https://help.github.com/en/github/working-with-github-pages/about-github-pages#types-of-github-pages-sites),修改配置文件的 `baseurl` 为项目名称,以斜杠开头,如:`/project`。 部署开始前,把 `_config.yml``url` 改为 `https://<username>.github.io`(或者你的私有域名,如:`https://yourdomain.com`)。另外,如果你想使用 [Project 类型网站](https://help.github.com/en/github/working-with-github-pages/about-github-pages#types-of-github-pages-sites),修改配置文件的 `baseurl` 为项目名称,以斜杠开头,如:`/project`。
假设你已经完成了 [初始化](#初始化)现在你可以选择下列其中一个方式去站点部署。 现在你可以选择下列其中一个方式去站点部署。
#### 部署到 GitHub Pages #### 部署到 GitHub Pages
由于安全原因GitHub Pages 的构建强制加了 `safe`参数,这导致了我们不能使用插件去创建所需的附加页面。因此,我们可以使用 GitHub Actions 去构建站点,把站点文件存储在一个新分支上,再指定该分支作为 Pages 服务的源。 由于安全原因GitHub Pages 的构建强制加了 `safe`参数,这导致了我们不能使用插件去创建所需的附加页面。因此,我们可以使用 GitHub Actions 去构建站点,把站点文件存储在一个新分支上,再指定该分支作为 Pages 服务的源。
1. 推送任意一个 commit 到 `origin/master` 以触发 GitHub Actions workflow。一旦 build 完毕并且成功,远端将会自动出现一个新分支 `gh-pages` 用来存储构建的站点文件。 确保你的 Jekyll 站点存在文件 `/.github/workflows/pages-deploy.yml`。没有的话,新建并填入[示例工作流][workflow]的内容, 注意参数 `on.push.branches` 的值必须和你的仓库默认分支名相同。
[workflow]:https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/.github/workflows/pages-deploy.yml.hook
在 GitHub 把你的仓库命名为 `<GH-USERNAME>.github.io`,然后:
1. 推送任意一个 commit 到 `origin/master` 以触发 GitHub Actions workflow。一旦 build 完毕并且成功,远端将会自动出现一个新分支 `gh-pages` 用来存储构建的站点文件。
2. 回到 GitHub 上的仓库, 通过 _Settings__Options__GitHub Pages_ 选择分支 `gh-pages` 作为[_发布源_](https://docs.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site):
2. 回到 GitHub 上的仓库, 通过 _Settings_
_Options__GitHub Pages_ 选择分支 `gh-pages` 作为[_发布源_](https://docs.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site):
![gh-pages-sources](https://cdn.jsdelivr.net/gh/cotes2020/chirpy-images/posts/20190809/gh-pages-sources.png) ![gh-pages-sources](https://cdn.jsdelivr.net/gh/cotes2020/chirpy-images/posts/20190809/gh-pages-sources.png)
3. 按照 GitHub 指示的地址去访问你的网站。 3. 按照 GitHub 指示的地址去访问你的网站。
#### 部署到其他 Pages 平台 #### 部署到其他 Pages 平台
@ -165,7 +195,7 @@ $ docker run -it --rm \
生成的静态文件将会在 `_site` 把内部的文件上传到服务器即可。 生成的静态文件将会在 `_site` 把内部的文件上传到服务器即可。
### 文档 ## 文档
若想要更多细节以及更佳的阅读体验,请参阅 [线上教程](https://chirpy.cotes.info/categories/tutorial/)。 与此同时,[Wiki](https://github.com/cotes2020/jekyll-theme-chirpy/wiki) 也有一份教程的拷贝。 若想要更多细节以及更佳的阅读体验,请参阅 [线上教程](https://chirpy.cotes.info/categories/tutorial/)。 与此同时,[Wiki](https://github.com/cotes2020/jekyll-theme-chirpy/wiki) 也有一份教程的拷贝。
@ -179,6 +209,12 @@ $ docker run -it --rm \
:tada: 感谢所有参与代码贡献的小伙伴, 他们的 GayHub ID 在这个[列表](https://github.com/cotes2020/jekyll-theme-chirpy/graphs/contributors)。 另外, 提交过 issues(或者未被合并 PR) 的高富帅和白富美也不会被遗忘,他/她们帮助报告 bug、分享新点子或者启发了我写出更通俗易懂的文档。 :tada: 感谢所有参与代码贡献的小伙伴, 他们的 GayHub ID 在这个[列表](https://github.com/cotes2020/jekyll-theme-chirpy/graphs/contributors)。 另外, 提交过 issues(或者未被合并 PR) 的高富帅和白富美也不会被遗忘,他/她们帮助报告 bug、分享新点子或者启发了我写出更通俗易懂的文档。
还有,感谢 [JetBrains][JB] 提供开源 License
[![JB-logo](https://cdn.jsdelivr.net/gh/cotes2020/chirpy-images/commons/jetbrains.svg)][JB]
[JB]:https://www.jetbrains.com/?from=jekyll-theme-chirpy
## 赞助 ## 赞助
如果您喜欢这个主题或者它对您有帮助,请考虑打赏作者:在 [项目主页](https://github.com/cotes2020/jekyll-theme-chirpy) 点击按钮 <kbd>:heart: Sponsor</kbd> 选择适合的链接即可完成(国内一般选第二个链接,支付宝/微信赞助),您的打赏将会极大地鼓励作者,并帮助作者更好地维护项目! 如果您喜欢这个主题或者它对您有帮助,请考虑打赏作者:在 [项目主页](https://github.com/cotes2020/jekyll-theme-chirpy) 点击按钮 <kbd>:heart: Sponsor</kbd> 选择适合的链接即可完成(国内一般选第二个链接,支付宝/微信赞助),您的打赏将会极大地鼓励作者,并帮助作者更好地维护项目!