diff --git a/README.md b/README.md index 0b04e0e..b2df54e 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,3 @@ -
- - EN / [中文](https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/docs/README.zh-CN.md) - -
-
# 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 `.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 `.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 `.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 __. -### 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 `.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 Save 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 -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 - [jb]: https://www.jetbrains.com/?from=jekyll-theme-chirpy diff --git a/docs/README.zh-CN.md b/docs/README.zh-CN.md deleted file mode 100644 index ab50240..0000000 --- a/docs/README.zh-CN.md +++ /dev/null @@ -1,245 +0,0 @@ -
- - [EN](https://github.com/cotes2020/jekyll-theme-chirpy#readme) / 中文 - -
- -
- - # 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) - -
- -## 功能一览 - -- 本地化外观语言 -- 可配置的主题颜色 -- 文章置顶 -- 文章最后修改日期 -- 文章目录 -- 自动推荐相关文章 -- 语法高亮 -- 二级目录 -- 数学表达式 -- 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 站点，命名为 `.github.io`，其中 `GH_USERNAME` 是您的 GitHub username。 - -#### 从 GitHub 上 Fork - -[Fork **Chirpy**](https://github.com/cotes2020/jekyll-theme-chirpy/fork) 并改名为 `.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 -``` - -稍候片刻，即可访问本地服务：__ - -### 部署 - -部署开始前，把 `_config.yml` 的 `url` 改为 `https://.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 把您的仓库命名为 `.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 - - - -[jb]: https://www.jetbrains.com/?from=jekyll-theme-chirpy -[cn-donation]: https://cotes.gitee.io/alipay-wechat-donation/