Merge branch 'feature/docs'
This commit is contained in:
Cotes Chung
commit
7337fa5f20
4 changed files with 79 additions and 434 deletions
37
.github/CONTRIBUTING.md
vendored
37
.github/CONTRIBUTING.md
vendored
|
|
@ -1,15 +1,42 @@
|
|||
# How to Contribute
|
||||
|
||||
I want to thank you for sparing time to improve this project! Here are some guidelines for contributing：
|
||||
We want to thank you for sparing time to improve this project! Here are some guidelines for contributing：
|
||||
|
||||
To ensure that the blog design is not confused, this project does not accept suggestions for design changes, such as color scheme, fonts, typography, etc. If your request is about an enhancement, it is recommended to first submit a [`Feature Request`](https://github.com/cotes2020/jekyll-theme-chirpy/issues/new?labels=enhancement&template=feature_request.md) issue to discuss whether your idea fits the project.
|
||||
To ensure that the blog design is not confused, this project does not accept suggestions for design changes, such as color scheme, fonts, typography, etc. If your request is about an enhancement, it is recommended to first submit a [_Feature Request_](https://github.com/cotes2020/jekyll-theme-chirpy/issues/new?labels=enhancement&template=feature_request.md) issue to discuss whether your idea fits the project.
|
||||
|
||||
## Basic Process
|
||||
|
||||
Generally, contribute to the project by:
|
||||
|
||||
1. Fork this project on GitHub and clone it locally.
|
||||
2. Create a new branch from `master` and give it a descriptive name (e.g., `my-new-feature`, `fix-a-bug`).
|
||||
3. After completing the development, commit and push to remote.
|
||||
4. Submit a new pull request.
|
||||
2. Create a new branch from the default branch and give it a descriptive name (e.g., `my-new-feature`, `fix-a-bug`).
|
||||
3. After completing the development, submit a new _Pull Request_.
|
||||
|
||||
## Modifying JavaScript
|
||||
|
||||
If your contribution involves JS modification, please read the following sections.
|
||||
|
||||
### Inline Scripts
|
||||
|
||||
If you need to add comments to the inline JS (the JS code between the tags `<script>` and `</script>`), please use `/**/` instead of two slashes `//`. Because the HTML will be compressed by [jekyll-compress-html](https://github.com/penibelst/jekyll-compress-html) during deployment, but it cannot handle the `//` properly. And this will disrupt the structure of the compressed HTML.
|
||||
|
||||
### External Scripts
|
||||
|
||||
If you need to add or modify JavaScripts in the directory `_javascript`, you need to install [Gulp.js](https://gulpjs.com/docs/en/getting-started/quick-start).
|
||||
|
||||
During development, real-time debugging can be performed through the following commands:
|
||||
|
||||
```console
|
||||
$ bash tools/run.sh
|
||||
```
|
||||
|
||||
Open another terminal tab and run:
|
||||
|
||||
```console
|
||||
$ gulp dev # Type 'Ctrl + C' to stop
|
||||
```
|
||||
|
||||
After debugging, run the command `gulp` (without any argument) will automatically output the compressed files to the directory `assests/js/dist/`.
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
170
README.md
170
README.md
|
|
@ -1,9 +1,3 @@
|
|||
<div align="right">
|
||||
|
||||
EN / [中文](https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/docs/README.zh-CN.md)
|
||||
|
||||
</div>
|
||||
|
||||
<div align="center">
|
||||
|
||||
# Chirpy Jekyll Theme
|
||||
|
|
@ -25,66 +19,32 @@
|
|||
## Features
|
||||
|
||||
- Localized Layout
|
||||
- Configurable Theme Mode
|
||||
- Dark/Light Theme Mode
|
||||
- Pinned Posts
|
||||
- Hierarchical Categories
|
||||
- Last Modified Date for Posts
|
||||
- Table of Contents
|
||||
- Automatically Recommend Related Posts
|
||||
- Auto-generated Related Posts
|
||||
- Syntax Highlighting
|
||||
- Mathematical Expressions
|
||||
- Mermaid Diagram & Flowchart
|
||||
- Disqus/Utterances Comments
|
||||
- Search
|
||||
- Atom Feeds
|
||||
- Disqus Comments
|
||||
- Google Analytics
|
||||
- GA Pageviews Reporting (Advanced)
|
||||
- GA Pageviews Reporting
|
||||
- SEO & Performance Optimization
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Follow the instructions in the [Jekyll Docs](https://jekyllrb.com/docs/installation/) to complete the installation of `Ruby`, `RubyGems`, `Jekyll`, and `Bundler`.
|
||||
## Quick Start
|
||||
|
||||
## Installation
|
||||
Before starting, please follow the instructions in the [Jekyll Docs](https://jekyllrb.com/docs/installation/) to complete the installation of `Ruby`, `RubyGems`, `Jekyll`, and `Bundler`.
|
||||
|
||||
### Creating a New Site
|
||||
### Step 1. Creating a New Site
|
||||
|
||||
There are two ways to create a new repository for this theme:
|
||||
Create a new repository from the [**Chirpy Starter**](https://github.com/cotes2020/chirpy-starter/generate) and name it `<GH_USERNAME>.github.io`, where `GH_USERNAME` represents your GitHub username.
|
||||
|
||||
- [**Using the Chirpy Starter**](#option-1-using-the-chirpy-starter) - Easy to upgrade, isolates irrelevant project files so you can focus on writing.
|
||||
- [**Forking on GitHub**](#option-2-forking-on-github) - Convenient for custom development, but difficult to upgrade. Unless you are familiar with Jekyll and are determined to tweak or contribute to this project, this approach is not recommended.
|
||||
|
||||
#### Option 1. Using the Chirpy Starter
|
||||
|
||||
Create a new repository from the [**Chirpy Starter**][use-starter] and name it `<GH_USERNAME>.github.io`, where `GH_USERNAME` represents your GitHub username.
|
||||
|
||||
#### Option 2. Forking on GitHub
|
||||
|
||||
[Fork **Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/fork) on GitHub and rename it to `<GH_USERNAME>.github.io`. Please note that the default branch code is in development. If you want the site to be stable, please switch to the [latest tag][latest-tag] and start writing.
|
||||
|
||||
And then execute:
|
||||
|
||||
```console
|
||||
$ bash tools/init.sh
|
||||
```
|
||||
|
||||
> **Note**: If you don't want to deploy your site on GitHub Pages, append option `--no-gh` at the end of the above command.
|
||||
|
||||
The above command will:
|
||||
|
||||
1. Removes some files or directories from your repository:
|
||||
|
||||
- `.travis.yml`
|
||||
- files under `_posts`
|
||||
- folder `docs`
|
||||
|
||||
2. If the option `--no-gh` is provided, the directory `.github` will be deleted. Otherwise, set up the GitHub Action workflow by removing the extension `.hook` of `.github/workflows/pages-deploy.yml.hook`, and then remove the other files and directories in the folder `.github`.
|
||||
|
||||
3. Removes item `Gemfile.lock` from `.gitignore`.
|
||||
|
||||
4. Creates a new commit to save the changes automatically.
|
||||
|
||||
### Installing Dependencies
|
||||
### Step 2. Installing Dependencies
|
||||
|
||||
Before running for the first time, go to the root directory of your site, and install dependencies as follows:
|
||||
|
||||
|
|
@ -92,32 +52,15 @@ Before running for the first time, go to the root directory of your site, and in
|
|||
$ bundle
|
||||
```
|
||||
|
||||
## Usage
|
||||
### Step 3. Running Local Server
|
||||
|
||||
### Configuration
|
||||
|
||||
Update the variables of `_config.yml` as needed. Some of them are typical options:
|
||||
|
||||
- `url`
|
||||
- `avatar`
|
||||
- `timezone`
|
||||
- `lang`
|
||||
|
||||
### Customing Stylesheet
|
||||
|
||||
If you need to customize the stylesheet, copy the theme's `assets/css/style.scss` to the same path on your Jekyll site, and then add the custom style at the end of the style file.
|
||||
|
||||
Starting from [`v4.1.0`][chirpy-4.1.0], if you want to overwrite the SASS variables defined in `_sass/addon/variables.scss`, create a new file `_sass/variables-hook.scss` and assign new values to the target variable in it.
|
||||
|
||||
### Running Local Server
|
||||
|
||||
You may want to preview the site contents before publishing, so just run it by:
|
||||
Run the following command in the root directory of the site:
|
||||
|
||||
```console
|
||||
$ bundle exec jekyll s
|
||||
```
|
||||
|
||||
Or run the site on Docker with the following command:
|
||||
Or run with Docker:
|
||||
|
||||
```console
|
||||
$ docker run -it --rm \
|
||||
|
|
@ -128,91 +71,13 @@ $ docker run -it --rm \
|
|||
|
||||
After a while, the local service will be published at _<http://127.0.0.1:4000>_.
|
||||
|
||||
### Deployment
|
||||
|
||||
Before the deployment begins, check out 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 starts with a slash, e.g, `/project-name`.
|
||||
|
||||
Now you can choose ONE of the following methods to deploy your Jekyll site.
|
||||
|
||||
#### Deploy by Using Github Actions
|
||||
|
||||
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 GitHub Pages service.
|
||||
|
||||
Quickly check the files needed for GitHub Actions build:
|
||||
|
||||
- Ensure your Jekyll site has the file `.github/workflows/pages-deploy.yml`. Otherwise, create a new one and fill in the contents of the [sample file][workflow], and the value of the `on.push.branches` should be the same as your repo's default branch name.
|
||||
|
||||
- Ensure your Jekyll site has file `tools/deploy.sh`. Otherwise, copy it from here to your Jekyll site.
|
||||
|
||||
- Furthermore, if you have committed `Gemfile.lock` to the repo, and your runtime system is not Linux, don't forget to update the platform list in the lock file:
|
||||
|
||||
```console
|
||||
$ bundle lock --add-platform x86_64-linux
|
||||
```
|
||||
|
||||
After the above steps, rename your repository to `<GH_USERNAME>.github.io` on GitHub.
|
||||
|
||||
Now publish your Jekyll 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 repository on GitHub. Select the tab _Settings_, then click _Pages_ in the left navigation bar, and then in the section **Source** of _GitHub Pages_, select the `/(root)` directory of branch `gh-pages` as the [publishing source][pages-src]. Remember to click <kbd>Save</kbd> before leaving.
|
||||
|
||||
|
||||
|
||||
3. Visit your website at the address indicated by GitHub.
|
||||
|
||||
#### Manually Build and Deploy
|
||||
|
||||
On self-hosted servers, you cannot enjoy the convenience of **GitHub Actions**. Therefore, you should build the site on your local machine and then upload the site files to the server.
|
||||
|
||||
Go to the root of the source project, and build your site as follows:
|
||||
|
||||
```console
|
||||
$ JEKYLL_ENV=production bundle exec jekyll b
|
||||
```
|
||||
|
||||
Or build the site on Docker:
|
||||
|
||||
```console
|
||||
$ docker run -it --rm \
|
||||
--env JEKYLL_ENV=production \
|
||||
--volume="$PWD:/srv/jekyll" \
|
||||
jekyll/jekyll \
|
||||
jekyll build
|
||||
```
|
||||
|
||||
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 the target server.
|
||||
|
||||
### Upgrading
|
||||
|
||||
It depends on how you use the theme:
|
||||
|
||||
- If you are using the theme gem (there will be `gem "jekyll-theme-chirpy"` in the `Gemfile`), editing the `Gemfile` and update the version number of the theme gem, for example:
|
||||
|
||||
```diff
|
||||
- gem "jekyll-theme-chirpy", "~> 3.2", ">= 3.2.1"
|
||||
+ gem "jekyll-theme-chirpy", "~> 3.3", ">= 3.3.0"
|
||||
```
|
||||
|
||||
And then execute the following command:
|
||||
|
||||
```console
|
||||
$ bundle update jekyll-theme-chirpy
|
||||
```
|
||||
|
||||
As the version upgrades, the critical files (for details, see the [Startup Template][starter]) and configuration options will change. Please refer to the [Upgrade Guide](https://github.com/cotes2020/jekyll-theme-chirpy/wiki/Upgrade-Guide) to keep your repo's files in sync with the latest version of the theme.
|
||||
|
||||
- If you forked from the source project (there will be `gemspec` in the `Gemfile` of your site), then merge the [latest upstream tags][latest-tag] into your Jekyll site to complete the upgrade.
|
||||
The merge is likely to conflict with your local modifications. Please be patient and careful to resolve these conflicts.
|
||||
|
||||
## Documentation
|
||||
|
||||
For more details and a better reading experience, please check out the [tutorials on the demo site](https://cotes2020.github.io/chirpy-demo/categories/tutorial/). In the meanwhile, a copy of the tutorial is also available on the [Wiki](https://github.com/cotes2020/jekyll-theme-chirpy/wiki). Please note that the tutorials on the demo website or Wiki are based on the latest release, and the features of `master` branch are usually ahead of the documentation.
|
||||
For more details on usage, please refer to the tutorial on the [demo website](https://cotes2020.github.io/chirpy-demo/). At the same time, a copy of the tutorial is also available on the [Wiki](https://github.com/cotes2020/jekyll-theme-chirpy/wiki). Please note that the tutorial is based on the [latest release](https://github.com/cotes2020/jekyll-theme-chirpy/releases), and the features of the default branch are usually ahead of the documentation.
|
||||
|
||||
## Contributing
|
||||
|
||||
The old saying, "Two heads are better than one." Consequently, welcome to report bugs, improve code quality or submit a new feature. For more information, see [contributing guidelines](.github/CONTRIBUTING.md).
|
||||
Welcome to report bugs, improve code quality or submit a new feature. For more information, see [contributing guidelines](.github/CONTRIBUTING.md).
|
||||
|
||||
## Credits
|
||||
|
||||
|
|
@ -234,13 +99,6 @@ If you like this theme or find it helpful, please consider sponsoring me, becaus
|
|||
|
||||
This work is published under [MIT](https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/LICENSE) License.
|
||||
|
||||
[starter]: https://github.com/cotes2020/chirpy-starter
|
||||
[use-starter]: https://github.com/cotes2020/chirpy-starter/generate
|
||||
[workflow]: https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/.github/workflows/pages-deploy.yml.hook
|
||||
[chirpy-4.1.0]: https://github.com/cotes2020/jekyll-theme-chirpy/releases/tag/v4.1.0
|
||||
[pages-src]: https://docs.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site
|
||||
[latest-tag]: https://github.com/cotes2020/jekyll-theme-chirpy/tags
|
||||
|
||||
<!-- ReadMe links -->
|
||||
|
||||
[jb]: https://www.jetbrains.com/?from=jekyll-theme-chirpy
|
||||
|
|
|
|||
|
|
@ -32,16 +32,19 @@ tags: [TAG] # TAG names should always be lowercase
|
|||
|
||||
### Timezone of Date
|
||||
|
||||
In order to accurately record the release date of a post, you should not only set up the `timezone` of `_config.yml` but also provide the post's timezone in variable `date` of its Front Matter block. Format: `+/-TTTT`, e.g. `+0800`.
|
||||
In order to accurately record the release date of a post, you should not only set up the `timezone` of _\_config.yml_ but also provide the post's timezone in variable `date` of its Front Matter block. Format: `+/-TTTT`, e.g. `+0800`.
|
||||
|
||||
### Categories and Tags
|
||||
|
||||
The `categories` of each post are designed to contain up to two elements, and the number of elements in `tags` can be zero to infinity. For instance:
|
||||
|
||||
```yaml
|
||||
---
|
||||
categories: [Animal, Insect]
|
||||
tags: [bee]
|
||||
---
|
||||
```
|
||||
|
||||
### Author Information
|
||||
|
||||
The author information of the post usually does not need to be filled in the _Front Matter_ , they will be obtained from variables `social.name` and the first entry of `social.links` of the configuration file by default. But you can also override it as follows:
|
||||
|
|
@ -56,7 +59,7 @@ author:
|
|||
|
||||
## Table of Contents
|
||||
|
||||
By default, the **T**able **o**f **C**ontents (TOC) is displayed on the right panel of the post. If you want to turn it off globally, go to `_config.yml` and set the value of variable `toc` to `false`. If you want to turn off TOC for a specific post, add the following to the post's [Front Matter](https://jekyllrb.com/docs/front-matter/):
|
||||
By default, the **T**able **o**f **C**ontents (TOC) is displayed on the right panel of the post. If you want to turn it off globally, go to _\_config.yml_ and set the value of variable `toc` to `false`. If you want to turn off TOC for a specific post, add the following to the post's [Front Matter](https://jekyllrb.com/docs/front-matter/):
|
||||
|
||||
```yaml
|
||||
---
|
||||
|
|
@ -66,7 +69,9 @@ toc: false
|
|||
|
||||
## Comments
|
||||
|
||||
Similar to TOC, the [Disqus](https://disqus.com/) comments are loaded by default in each post, and the global switch is defined by variable `comments` in file `_config.yml` . If you want to close the comment for a specific post, add the following to the **Front Matter** of the post:
|
||||
The global switch of comments is defined by variable `comments.active` in the file _\_config.yml_. After selecting a comment system for this variable, comments will be turned on for all posts.
|
||||
|
||||
If you want to close the comment for a specific post, add the following to the **Front Matter** of the post:
|
||||
|
||||
```yaml
|
||||
---
|
||||
|
|
@ -98,26 +103,7 @@ Then you can use it like other markdown languages: surround the graph code with
|
|||
|
||||
## Images
|
||||
|
||||
### Preview image
|
||||
|
||||
If you want to add an image to the top of the post contents, specify the attribute `src`, `width`, `height`, and `alt` for the image:
|
||||
|
||||
```yaml
|
||||
---
|
||||
image:
|
||||
src: /path/to/image/file
|
||||
width: 1000 # in pixels
|
||||
height: 400 # in pixels
|
||||
alt: image alternative text
|
||||
---
|
||||
```
|
||||
|
||||
Except for `alt`, all other options are necessary, especially the `width` and `height`, which are related to user experience and web page loading performance. Later section ["Image size"](#image-size) will also mention this.
|
||||
|
||||
Starting from _Chirpy v5.0.0_, the attributes `height` and `width` support abbreviations: `height` → `h`, `width` → `w`.
|
||||
|
||||
|
||||
### Image caption
|
||||
### Caption
|
||||
|
||||
Add italics to the next line of an image，then it will become the caption and appear at the bottom of the image:
|
||||
|
||||
|
|
@ -127,7 +113,7 @@ _Image Caption_
|
|||
```
|
||||
{: .nolineno}
|
||||
|
||||
### Image size
|
||||
### Size
|
||||
|
||||
In order to prevent the page content layout from shifting when the image is loaded, we should set the width and height for each image:
|
||||
|
||||
|
|
@ -143,7 +129,7 @@ Starting from _Chirpy v5.0.0_, `height` and `width` support abbreviations (`heig
|
|||
```
|
||||
{: .nolineno}
|
||||
|
||||
### Image position
|
||||
### Position
|
||||
|
||||
By default, the image is centered, but you can specify the position by using one of the classes `normal`, `left`, and `right`. For example:
|
||||
|
||||
|
|
@ -172,7 +158,7 @@ By default, the image is centered, but you can specify the position by using one
|
|||
|
||||
> **Limitation**: Once the position of the image is specified, the image caption should not be added.
|
||||
|
||||
### Image shadow
|
||||
### Shadow
|
||||
|
||||
The screenshots of the program window can be considered to show the shadow effect, and the shadow will be visible in the `light` mode:
|
||||
|
||||
|
|
@ -183,7 +169,7 @@ The screenshots of the program window can be considered to show the shadow effec
|
|||
|
||||
### CDN URL
|
||||
|
||||
If you host the images on the CDN, you can save the time of repeatedly writing the CDN URL by assigning the variable `img_cdn` of `_config.yml` file:
|
||||
If you host the images on the CDN, you can save the time of repeatedly writing the CDN URL by assigning the variable `img_cdn` of _\_config.yml_ file:
|
||||
|
||||
```yaml
|
||||
img_cdn: https://cdn.com
|
||||
|
|
@ -206,7 +192,7 @@ The parsing result will automatically add the CDN prefix `https://cdn.com` befor
|
|||
```
|
||||
{: .nolineno}
|
||||
|
||||
### Image path
|
||||
### Image Path
|
||||
|
||||
When a post contains many images, it will be a time-consuming task to repeatedly define the path of the images. To solve this, we can define this path in the YAML block of the post:
|
||||
|
||||
|
|
@ -231,6 +217,25 @@ The output will be:
|
|||
```
|
||||
{: .nolineno }
|
||||
|
||||
|
||||
### Preview Image
|
||||
|
||||
If you want to add an image to the top of the post contents, specify the attribute `src`, `width`, `height`, and `alt` for the image:
|
||||
|
||||
```yaml
|
||||
---
|
||||
image:
|
||||
src: /path/to/image/file
|
||||
width: 1000 # in pixels
|
||||
height: 400 # in pixels
|
||||
alt: image alternative text
|
||||
---
|
||||
```
|
||||
|
||||
Except for `alt`, all other options are necessary, especially the `width` and `height`, which are related to user experience and web page loading performance. The above section "[Size](#size)" also mentions this.
|
||||
|
||||
Starting from _Chirpy v5.0.0_, the attributes `height` and `width` can be abbreviated: `height` → `h`, `width` → `w`. In addition, the [`img_path`](#image-path) can also be passed to the preview image, that is, when it has been set, the attribute `src` only needs the image file name.
|
||||
|
||||
## Pinned Posts
|
||||
|
||||
You can pin one or more posts to the top of the home page, and the fixed posts are sorted in reverse order according to their release date. Enable by:
|
||||
|
|
|
|||
|
|
@ -1,245 +0,0 @@
|
|||
<div align="right">
|
||||
|
||||
[EN](https://github.com/cotes2020/jekyll-theme-chirpy#readme) / 中文
|
||||
|
||||
</div>
|
||||
|
||||
<div align="center">
|
||||
|
||||
# Chirpy Jekyll Theme
|
||||
|
||||
一款简约而强大、采用响应式设计的 Jekyll 主题，适合展示专业写作内容。
|
||||
|
||||
[](https://rubygems.org/gems/jekyll-theme-chirpy)
|
||||
[](https://github.com/cotes2020/jekyll-theme-chirpy/actions?query=branch%3Amaster+event%3Apush)
|
||||
[](https://www.codacy.com/gh/cotes2020/jekyll-theme-chirpy/dashboard?utm_source=github.com&utm_medium=referral&utm_content=cotes2020/jekyll-theme-chirpy&utm_campaign=Badge_Grade)
|
||||
[](https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/LICENSE)
|
||||
[](https://996.icu)
|
||||
|
||||
[**线上体验 →**](https://cotes2020.github.io/chirpy-demo)
|
||||
|
||||
[](https://cotes2020.github.io/chirpy-demo)
|
||||
|
||||
</div>
|
||||
|
||||
## 功能一览
|
||||
|
||||
- 本地化外观语言
|
||||
- 可配置的主题颜色
|
||||
- 文章置顶
|
||||
- 文章最后修改日期
|
||||
- 文章目录
|
||||
- 自动推荐相关文章
|
||||
- 语法高亮
|
||||
- 二级目录
|
||||
- 数学表达式
|
||||
- Mermaid 图表
|
||||
- 搜索
|
||||
- Atom 订阅
|
||||
- Disqus 评论
|
||||
- Google 分析
|
||||
- GA 浏览报告（高级功能）
|
||||
- SEO 优化
|
||||
- 网站性能优化
|
||||
|
||||
## 前提要求
|
||||
|
||||
参考 [Jekyll Docs](https://jekyllrb.com/docs/installation/) 安装 `Ruby`，`RubyGems`，`Jekyll` 和 `Bundler`。
|
||||
|
||||
## 安装
|
||||
|
||||
### 创建新仓库
|
||||
|
||||
有两种方式可以创建一个使用本主题的仓库：
|
||||
|
||||
- [**使用 Chirpy Starter**](#使用-chirpy-starter) - 易于版本升级，隔离无关的主题项目文件，让您的仓库舒适清爽。
|
||||
- [**从 GitHub 上 Fork**](#从-github-上-fork) - 对个性化二次开发友好，但是难于升级。除非您决定魔改此款主题或者参与代码贡献，否则不推荐使用此方式。
|
||||
|
||||
#### 使用 Chirpy Starter
|
||||
|
||||
[使用 Chirpy Starter][use-starter] 来快速创建 Jekyll 站点，命名为 `<GH_USERNAME>.github.io`，其中 `GH_USERNAME` 是您的 GitHub username。
|
||||
|
||||
#### 从 GitHub 上 Fork
|
||||
|
||||
[Fork **Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/fork) 并改名为 `<GH_USERNAME>.github.io`。友情提示：默认分支的代码处于开发状态，如果您想博客更加稳定，请切换到最新的 [Tag][latest-tag] 开始写作。
|
||||
|
||||
接着执行文件初始化:
|
||||
|
||||
```console
|
||||
$ bash tools/init.sh
|
||||
```
|
||||
|
||||
> **注**：如果您不打算部署到 GitHub Pages， 在上述命令后附加参数选项 `--no-gh`。
|
||||
|
||||
上述脚本将会:
|
||||
|
||||
1. 从您的仓库中删除了:
|
||||
|
||||
- `.travis.yml`
|
||||
- `_posts` 下的文件
|
||||
- `docs` 目录
|
||||
|
||||
2. 如果使用了参数 `--no-gh`，则会怒删文件夹 `.github`。否则，配置 GitHub Actions：把 `.github/workflows/pages-deploy.yml.hook` 的后缀 `.hook` 去除，然后删除 `.github` 里的其他目录和文件。
|
||||
|
||||
3. 从 `.gitignore` 中删除 `Gemfile.lock`。
|
||||
|
||||
4. 自动提交一个 Commit 以保存上述文件的更改。
|
||||
|
||||
### 安装依赖：
|
||||
|
||||
首次运行本项目，需要先安装依赖：
|
||||
|
||||
```console
|
||||
$ bundle
|
||||
```
|
||||
|
||||
## 使用
|
||||
|
||||
### 配置文件
|
||||
|
||||
根据个人需要去修改 `_config.yml` 的变量，大部分都有注释介绍用法。典型的几个选项是：
|
||||
|
||||
- `url`
|
||||
- `avatar`
|
||||
- `timezone`
|
||||
- `lang`
|
||||
|
||||
### 自定义样式
|
||||
|
||||
如果您需要自定义样式， 拷贝主题的文件 `assets/css/style.scss` 到您站点的相同路径上，然后在该文件末尾添加样式。
|
||||
|
||||
自 [`v4.1.0`][chirpy-4.1.0] 起，如果您想覆盖文件 `_sass/addon/variables.scss` 里定义的 SASS 变量的默认值，新建文件 `_sass/variables-hook.scss`，然后重写您需要的变量即可。
|
||||
|
||||
### 本地运行
|
||||
|
||||
发布之前，在本地预览:
|
||||
|
||||
```terminal
|
||||
$ bundle exec jekyll s
|
||||
```
|
||||
|
||||
或者用 Docker 运行:
|
||||
|
||||
```terminal
|
||||
$ docker run -it --rm \
|
||||
--volume="$PWD:/srv/jekyll" \
|
||||
-p 4000:4000 jekyll/jekyll \
|
||||
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`。
|
||||
|
||||
现在您可以选择下列其中一个方式去站点部署。
|
||||
|
||||
#### 使用 GitHub Actions 部署
|
||||
|
||||
由于安全原因，默认的 GitHub Pages 的构建强制加了 `safe`参数，这导致了我们不能使用插件去创建所需的附加页面。因此，我们可以使用 GitHub Actions 去构建站点，把站点文件存储在一个新分支上，再指定该分支作为 Pages 服务的源。
|
||||
|
||||
快速检查 GitHub Actions 构建需要的文件:
|
||||
|
||||
- 确保您的 Jekyll 站点存在文件 `.github/workflows/pages-deploy.yml`。没有的话，新建并填入「[示例 Workflow][workflow]」的内容，注意参数 `on.push.branches` 的值必须和您的仓库默认分支名相同。
|
||||
|
||||
- 检查您的 Jekyll 站点是否有文件 `tools/deploy.sh`。没有的话， 从本仓库拷贝到您的 Jekyll 项目。
|
||||
|
||||
- 再者，如果您已经把文件 `Gemfile.lock` 提交到了仓库里面，并且您运行本项目的操作系统不是 Linux，需要添加新的平台信息：
|
||||
|
||||
```console
|
||||
$ bundle lock --add-platform x86_64-linux
|
||||
```
|
||||
|
||||
完成上述条目后，到 GitHub 把您的仓库命名为 `<GH-USERNAME>.github.io`，然后开始发布：
|
||||
|
||||
1. 推送任意一个 commit 到 `origin/master` 以触发 GitHub Actions workflow。一旦 build 完毕并且成功，远端将会自动出现一个新分支 `gh-pages` 用来存储构建的站点文件。
|
||||
|
||||
2. 回到 GitHub 上的仓库，选择标签 _Settings_ → 点击左侧导航栏的 _Pages_ → _GitHub Pages_ 选择分支 `gh-pages` 的 `/(root)` 作为「[发布源][pages-src]」:
|
||||
|
||||
|
||||
|
||||
3. 按照 GitHub 指示的地址去访问您的网站。
|
||||
|
||||
#### 手动构建部署
|
||||
|
||||
在 GitHub 之外的平台，就没法享受 **GitHub Actions** 的便利了。因此您需要在本地构建站点，然后推送站点文件到服务器上。
|
||||
|
||||
在项目根目录，运行:
|
||||
|
||||
```console
|
||||
$ JEKYLL_ENV=production bundle exec jekyll b
|
||||
```
|
||||
|
||||
或者通过 Docker 构建:
|
||||
|
||||
```terminal
|
||||
$ docker run -it --rm \
|
||||
--env JEKYLL_ENV=production \
|
||||
--volume="$PWD:/srv/jekyll" \
|
||||
jekyll/jekyll \
|
||||
jekyll build
|
||||
```
|
||||
|
||||
生成的静态文件将会在 `_site`， 把内部的文件上传到服务器即可。
|
||||
|
||||
### 升级
|
||||
|
||||
这取决于您如何使用这个 theme：
|
||||
|
||||
- 如果您是使用 theme gem（`Gemfile` 会有 `gem "jekyll-theme-chirpy"`），编辑 `Gemfile` 并更新 them gem 的版本号，譬如：
|
||||
|
||||
```diff
|
||||
- gem "jekyll-theme-chirpy", "~> 3.2", ">= 3.2.1"
|
||||
+ gem "jekyll-theme-chirpy", "~> 3.3", ">= 3.3.0"
|
||||
```
|
||||
|
||||
接着执行以下命令：
|
||||
|
||||
```console
|
||||
$ bundle update jekyll-theme-chirpy
|
||||
```
|
||||
|
||||
随着 theme 版本的升级，运行站点的必要文件（详见 [Chirpy Starter][starter]）以及配置选项会出现变化，请参阅「[升级指南](https://github.com/cotes2020/jekyll-theme-chirpy/wiki/Upgrade-Guide)」的改动细节去保持您仓库中的相关文件同步到最新版本。
|
||||
|
||||
- 如果您是以 fork 的方式使用（您站点的 `Gemfile` 会有 `gemspec`），那么合并上游 [最新的 tag][latest-tag] 到您的 Repo 以完成升级。期间很有可能会产生冲突 (conflicts)，请务必耐心谨慎地解决它们。
|
||||
|
||||
## 文档
|
||||
|
||||
若想要更多细节以及更佳的阅读体验，请参阅「[线上教程](https://cotes2020.github.io/chirpy-demo/categories/tutorial/)」。 与此同时，「[Wiki](https://github.com/cotes2020/jekyll-theme-chirpy/wiki)」也有一份教程的拷贝。请注意，Demo 网站和 Wiki 上的文档都是基于最新的发行版本，而 `master` 分支的功能往往领先于现有文档。
|
||||
|
||||
## 参与贡献
|
||||
|
||||
三人行必有我师，欢迎提报告 bug，帮助改进代码质量，或者提交新功能。具体操作规则请参考「[贡献指南](../.github/CONTRIBUTING.md)」，谢谢 🙏。
|
||||
|
||||
## 鸣谢
|
||||
|
||||
此款主题的开发主要基于 [Jekyll](https://jekyllrb.com/) 生态、[Bootstrap](https://getbootstrap.com/)、[Font Awesome](https://fontawesome.com/) 和其他一些出色的工具 (相关文件中可以找到这些工具的版权信息)。头像和图标的设计来自于 [Clipart Max](https://www.clipartmax.com/middle/m2i8b1m2K9Z5m2K9_ant-clipart-childrens-ant-cute/)。
|
||||
|
||||
:tada: 感谢所有参与代码贡献的小伙伴，他们的 GayHub ID 在这个「[列表](https://github.com/cotes2020/jekyll-theme-chirpy/graphs/contributors)」。 另外，提交过 issues（或者未被合并 PR）的高富帅和白富美也不会被遗忘，他/她们帮助报告 bug、分享新点子或者启发了我写出更通俗易懂的文档。
|
||||
|
||||
还有，感谢 [JetBrains][jb] 提供开源 License！
|
||||
|
||||
## 赞助
|
||||
|
||||
如果您喜欢此款主题或者它对您有帮助，请考虑打赏作者，您的支持将会极大地鼓励作者，并帮助作者更好地维护项目！
|
||||
|
||||
[](https://ko-fi.com/coteschung)
|
||||
[][cn-donation]
|
||||
[][cn-donation]
|
||||
|
||||
## 许可证书
|
||||
|
||||
本项目开源，基于 [MIT](https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/LICENSE) 许可。
|
||||
|
||||
[starter]: https://github.com/cotes2020/chirpy-starter
|
||||
[use-starter]: https://github.com/cotes2020/chirpy-starter/generate
|
||||
[workflow]: https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/.github/workflows/pages-deploy.yml.hook
|
||||
[chirpy-4.1.0]: https://github.com/cotes2020/jekyll-theme-chirpy/releases/tag/v4.1.0
|
||||
[pages-src]: https://docs.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site
|
||||
[latest-tag]: https://github.com/cotes2020/jekyll-theme-chirpy/tags
|
||||
|
||||
<!-- ReadMe links -->
|
||||
|
||||
[jb]: https://www.jetbrains.com/?from=jekyll-theme-chirpy
|
||||
[cn-donation]: https://cotes.gitee.io/alipay-wechat-donation/
|
||||
Loading…
Reference in a new issue