web/docs/README_zh-CN.md

Chirpy

🌏 English • 简体中文

一个不一样的 Jekyll 主题，采用响应式设计，方便记录、管理、分享你的知识和经验。懂的进 »

⚠️ 中文版文档存在更新不及时的风险（开源文档以英文为主，请见谅）。如果发现中、英文内容不匹配的情况，一切以英文版内容为准。如果您愿意的话，可提交 issuse 提醒作者更新中文版 README，谢谢。

目录

• 功能预览
• 安装
• 运行指南
• 参与贡献
• 感谢
• 赞助
• 许可证书

功能预览

• 文章置顶
• 可配置的全局主题颜色
• 文章最后修改日期
• 文章目录
• 自动推荐相关文章
• 语法高亮
• 二级目录
• 数学表达式
• 搜索
• Atom 订阅
• Disqus 评论
• Google 分析
• GA 浏览报告（高级功能）
• SEO 优化
• 网站性能优化

安装

准备工作

按照 Jekyll 官方文档 完成基础环境的安装 (Ruby，RubyGem，Bundler)。

为了使用项目内免费提供的脚本工具增进写作体验，如果你的机器系统是 Debian 或者 macOS，则需要确保安装了 GNU coreutils。否则，通过以下方式获得：

• Debian

$ sudo apt-get install coreutils

• macOS

$ brew install coreutils

接着，fork 一份代码，然后克隆你 Fork 的仓库到本地机器上。

$ git clone git@github.com:USER/jekyll-theme-chirpy.git -b master

把上述的USER 替换为你的 GitHub username。

安装 Jekyll 插件

本地首次运行或编译，请在项目根目录下运行:

$ bundle install

bundle 命令会自动安装 Gemfile 内声明的依赖插件.

运行指南

文件目录

下面是主要的文件目录：

jekyll-theme-chirpy/
├── _data
├── _includes      
├── _layouts
├── _posts          # posts stay here
├── _scripts
├── .travis.yml     # remove it
├── .github         # remove this, too
├── assets      
├── tabs
│   └── about.md    # the ABOUT page
├── .gitignore
├── 404.html
├── Gemfile
├── LICENSE
├── README.md
├── _config.yml     # configuration file
├── tools           # script tools
├── docs
├── feed.xml
├── index.html
├── robots.txt
└── sitemap.xml

你需要将以下文件或目录删除:

• .travis.yml
• .github

配置文件

根据个人需要去修改 _config.yml 的变量，大部分都有注释介绍用法。

• url

  定义网站 URL，注意结尾不带 /。格式： <protocol>://<domain>.

• avatar

  定义头像，示例的文件放置在：/assets/img/sample/avatar.jpg. 把它换成你自己的头像，路径不限定，越小越好。(压缩图像体积可上这个网站：https://tinypng.com/ ).

• timezone

  定义时区 ，默认为 亚洲/上海，如果肉身翻墙要换城市可在此列表找到： TimezoneConverter 或者 Wikipedia.

• theme_mode

  定义颜色方案，有三种可选：:

  • dual - 自动跟随系统的 深色/浅色 设置，当系统或者浏览器不支持深色模式，则默认显示为浅色模式。无论如何，侧边栏左下角都会显示一个颜色切换按钮。
  • dark - 全程深色模式。
  • light - 全程浅色模式。

本地运行

使用以下工具可轻松运行:

$ bash tools/run.sh

访问本地服务： http://localhost:4000

如果你想在本地服务运行后，把修改源文件的更改实时刷新，可使用选项 -r (或 --realtime)，不过要先安装依赖 fswatch 。

部署到 GitHub Pages

部署开始前，把 _config.yml 的 url 改为 https://<username>.github.io(或者你的私有域名，如：https://yourdomain.com)。另外，如果你想使用 Project 类型网站，修改配置文件的 baseurl 为项目名称，以斜杠开头，如：/project。

方法 1: 由 GitHub Pages 生成站点

依照本方法，你可以直接把源码推送到远端仓库。

注: 如果你想使用任何不在这个列表上的插件，越过此方法，直接看 方法 2: 本地构建.

1. 仓库改名为:

站点类型	仓库名称
User or Organization	<username>.github.io
Project	<username>.github.io 以外的名字，譬如 project

2. 提交本地更改，然后运行:

$ bash tools/init.sh

注: 最后更新 列表根据文章的 git 修改记录生成，所以运行前先把 _posts 目录的修改提交。

它会自动生成文章的 最后修改日期 和 分类 / 标签 页面，并自动提交一个 commit。输出日志类似如下：

[INFO] Success to update lastmod for 4 post(s).
[INFO] Succeed! 3 category-pages created.
[INFO] Succeed! 4 tag-pages created.
[Automation] Updated the Categories, Tags, Lastmod for post(s).
 11 files changed, 46 insertions(+), 3 deletions(-)
 ...
Updated the Categories, Tags, Lastmod for post(s).

3. 推送到 origin/master 然后到 GitHub 网页为该项目开启 Pages 服务。

4. 网站将运行在：

站点类型	网站 URL
User or Organization	https://<username>.github.io/
Project	https://<username>.github.io/project/

方法 2: 本地构建

由于安全原因，GitHub Pages 不允许第三方插件运行，如果你想突破规则，就要本地构建站点内容。

1. 到 GitHub 网页，创建一个新的仓库，根据以下规则命名:

站点类型	仓库名称
User or Organization	<username>.github.io
Project	<username>.github.io 以外的名字， 例如 project

然后 Clone 新仓库到本地。

2. 构建站点:

$ bash tools/build.sh -d /path/to/local/project/

project 为新仓库名称。

生成的静态文件将会在 /path/to/local/project. 把新仓库的修改提交并推送到远端 master 分支.

3. 回到 GithHub 网页，为该仓库开启 Pages 服务。

4. 网站将运行在:

站点类型	站点 URL
User or Organization	https://<username>.github.io/
Project	https://<username>.github.io/project/

结束工作

无论你选择了哪种方式部署网站到 GitHub Pages, 请开启 HTTPS 功能。具体细节参考官方说明：Securing your GitHub Pages site with HTTPS。

文档

若想要更多细节以及更佳的阅读体验，请参阅 线上教程。 与此同时，Wiki 也有一份教程的拷贝。

参与贡献

三人行必有我师，欢迎提报告 bug, 帮助改进代码质量，或者提交新功能。具体操作规则请参考 贡献指南，谢谢 🙏。

感谢

这个主题的开发主要基于 Jekyll 生态、Bootstrap、Font Awesome 和其他一些出色的工具 (相关文件中可以找到这些工具的版权信息).

🎉感谢所有参与代码贡献的小伙伴, 他们的 GayHub ID 在这个列表。 另外, 提交过 issues(或者未被合并 PR) 的高富帅和白富美也不会被遗忘,他/她们帮助报告 bug、分享新点子或者启发了我写出更通俗易懂的文档。

赞助

如果您喜欢这个主题或者它对您有帮助，请考虑打赏作者：在 项目主页 点击按钮 ❤️Sponsor 选择适合的链接即可完成（国内一般选第二个链接，支付宝/微信赞助），您的打赏将会极大地鼓励作者，并帮助作者更好地维护项目！

许可证书

本项目开源，基于 MIT 许可。