Simplify the README
This commit is contained in:
parent
b91b6711b0
commit
65a38c8f22
2 changed files with 14 additions and 401 deletions
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">
|
<div align="center">
|
||||||
|
|
||||||
# Chirpy Jekyll Theme
|
# Chirpy Jekyll Theme
|
||||||
|
@ -25,66 +19,32 @@
|
||||||
## Features
|
## Features
|
||||||
|
|
||||||
- Localized Layout
|
- Localized Layout
|
||||||
- Configurable Theme Mode
|
- Dark/Light Theme Mode
|
||||||
- Pinned Posts
|
- Pinned Posts
|
||||||
- Hierarchical Categories
|
- Hierarchical Categories
|
||||||
- Last Modified Date for Posts
|
- Last Modified Date for Posts
|
||||||
- Table of Contents
|
- Table of Contents
|
||||||
- Automatically Recommend Related Posts
|
- Auto-generated Related Posts
|
||||||
- Syntax Highlighting
|
- Syntax Highlighting
|
||||||
- Mathematical Expressions
|
- Mathematical Expressions
|
||||||
- Mermaid Diagram & Flowchart
|
- Mermaid Diagram & Flowchart
|
||||||
|
- Disqus/Utterances Comments
|
||||||
- Search
|
- Search
|
||||||
- Atom Feeds
|
- Atom Feeds
|
||||||
- Disqus Comments
|
|
||||||
- Google Analytics
|
- Google Analytics
|
||||||
- GA Pageviews Reporting (Advanced)
|
- GA Pageviews Reporting
|
||||||
- SEO & Performance Optimization
|
- 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.
|
### Step 2. Installing Dependencies
|
||||||
- [**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
|
|
||||||
|
|
||||||
Before running for the first time, go to the root directory of your site, and install dependencies as follows:
|
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
|
$ bundle
|
||||||
```
|
```
|
||||||
|
|
||||||
## Usage
|
### Step 3. Running Local Server
|
||||||
|
|
||||||
### Configuration
|
Run the following command in the root directory of the site:
|
||||||
|
|
||||||
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:
|
|
||||||
|
|
||||||
```console
|
```console
|
||||||
$ bundle exec jekyll s
|
$ bundle exec jekyll s
|
||||||
```
|
```
|
||||||
|
|
||||||
Or run the site on Docker with the following command:
|
Or run with Docker:
|
||||||
|
|
||||||
```console
|
```console
|
||||||
$ docker run -it --rm \
|
$ 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>_.
|
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.
|
|
||||||
|
|
||||||
![gh-pages-sources](https://cdn.jsdelivr.net/gh/cotes2020/chirpy-images@f4e0354b674f65a53b8917f0f786ed2956898cc1/posts/20190809/gh-pages-sources.png)
|
|
||||||
|
|
||||||
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
|
## 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
|
## 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
|
## 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.
|
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 -->
|
<!-- ReadMe links -->
|
||||||
|
|
||||||
[jb]: https://www.jetbrains.com/?from=jekyll-theme-chirpy
|
[jb]: https://www.jetbrains.com/?from=jekyll-theme-chirpy
|
||||||
|
|
|
@ -1,245 +0,0 @@
|
||||||
<div align="right">
|
|
||||||
|
|
||||||
[EN](https://github.com/cotes2020/jekyll-theme-chirpy#readme) / 中文
|
|
||||||
|
|
||||||
</div>
|
|
||||||
|
|
||||||
<div align="center">
|
|
||||||
|
|
||||||
# Chirpy Jekyll Theme
|
|
||||||
|
|
||||||
一款简约而强大、采用响应式设计的 Jekyll 主题,适合展示专业写作内容。
|
|
||||||
|
|
||||||
[![Gem Version](https://img.shields.io/gem/v/jekyll-theme-chirpy?color=brightgreen)](https://rubygems.org/gems/jekyll-theme-chirpy)
|
|
||||||
[![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://app.codacy.com/project/badge/Grade/4e556876a3c54d5e8f2d2857c4f43894)](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)
|
|
||||||
[![GitHub license](https://img.shields.io/github/license/cotes2020/jekyll-theme-chirpy.svg)](https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/LICENSE)
|
|
||||||
[![996.icu](https://img.shields.io/badge/link-996.icu-%23FF4D5B.svg)](https://996.icu)
|
|
||||||
|
|
||||||
[**线上体验 →**](https://cotes2020.github.io/chirpy-demo)
|
|
||||||
|
|
||||||
[![Devices Mockup](https://cdn.jsdelivr.net/gh/cotes2020/chirpy-images@f4e0354b674f65a53b8917f0f786ed2956898cc1/commons/devices-mockup.png)](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]」:
|
|
||||||
|
|
||||||
![gh-pages-sources](https://cdn.jsdelivr.net/gh/cotes2020/chirpy-images@f4e0354b674f65a53b8917f0f786ed2956898cc1/posts/20190809/gh-pages-sources.png)
|
|
||||||
|
|
||||||
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!
|
|
||||||
|
|
||||||
## 赞助
|
|
||||||
|
|
||||||
如果您喜欢此款主题或者它对您有帮助,请考虑打赏作者,您的支持将会极大地鼓励作者,并帮助作者更好地维护项目!
|
|
||||||
|
|
||||||
[![Ko-fi](https://img.shields.io/badge/-请作者喝杯咖啡-ff5f5f?logo=ko-fi&logoColor=white)](https://ko-fi.com/coteschung)
|
|
||||||
[![Wechat Pay](https://img.shields.io/badge/-微信打赏作者-brightgreen?logo=wechat&logoColor=white)][cn-donation]
|
|
||||||
[![Alipay](https://img.shields.io/badge/-支付宝打赏作者-blue?logo=alipay&logoColor=white)][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