Cotes Chung a8b8a379f6 Improve the docs

- Add missing url references in the tutorial
- Add gem version badge in README

2021-01-30 02:00:34 +08:00

8.7 KiB

Raw Blame History

Chirpy

Language: English | 简体中文

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

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

功能一览

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

前提要求

参考 Jekyll Docs 安装 Ruby，RubyGems，Jekyll 和 Bundler，Docker 粉可免。

安装

有二法可得此主题:

从 RubyGems 安装
从 GitHub 上 Fork

Rubygems 安装

在你的 Jekyll 站点的 Gemfile 添加:

gem "jekyll-theme-chirpy"

然后，添加这行到你的 Jekyll 站点的 _config.yml:

theme: jekyll-theme-chirpy

接着执行:

$ bundle

最后, 拷贝额外所需主题的 gem 文件（详见 starter 项目的文件目录）至你的 Jekyll 站点, 然后把主题的 _config.yml 全部内容附加到你的 Jekyll 站点的同名文件。

提示: 定位主题的 gem 文件，可以执行:

$ bundle info --path jekyll-theme-chirpy

或者你可以使用 starter template 来快速创建 Jekyll 站点，以省去复制主题 gem 文件的时间。

在 GitHub 上 Fork

Fork Chirpy 然后克隆到本地。

安装依赖：

$ bundle

接着执行文件初始化:

$ bash tools/init.sh

如果你不打算部署到 GitHub Pages, 在上述命令后附加参数选项 --no-gh。

上述脚本完成了以下工作:

从你的仓库中删除了:
- .travis.yml
- _posts 下的文件
- docs 目录
如果使用了参数 --no-gh，则会怒删 .github。否则，将会配置 GitHub Actions：把 .github/workflows/pages-deploy.yml.hook 的后缀 .hook 去除，然后删除 .github 里的其他目录和文件。
自动提交一个 Commit 以保存上述文件的更改。

使用

配置文件

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

url
avatar
timezone
theme_mode

本地运行

发布之前，在本地预览:

$ bundle exec jekyll s

或者用 Docker 运行:

$ 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 类型网站，修改配置文件的 baseurl 为项目名称，以斜杠开头，如：/project。

现在你可以选择下列其中一个方式去站点部署。

部署到 GitHub Pages

由于安全原因，GitHub Pages 的构建强制加了 safe参数，这导致了我们不能使用插件去创建所需的附加页面。因此，我们可以使用 GitHub Actions 去构建站点，把站点文件存储在一个新分支上，再指定该分支作为 Pages 服务的源。

快速检查 GitHub Actions 构建需要的文件:

确保你的 Jekyll 站点存在文件 /.github/workflows/pages-deploy.yml。没有的话，新建并填入示例工作流的内容, 注意参数 on.push.branches 的值必须和你的仓库默认分支名相同。
检查你的 Jekyll 站点是否有文件 /tools/test.sh 和 /tools/deploy.sh. 没有的话, 从本仓库拷贝到你的 Jekyll 项目.

在 GitHub 把你的仓库命名为 <GH-USERNAME>.github.io，然后：

推送任意一个 commit 到 origin/master 以触发 GitHub Actions workflow。一旦 build 完毕并且成功，远端将会自动出现一个新分支 gh-pages 用来存储构建的站点文件。
回到 GitHub 上的仓库，通过 Settings → Options → GitHub Pages 选择分支 gh-pages 作为发布源:
按照 GitHub 指示的地址去访问你的网站。

部署到其他 Pages 平台

在 GitHub 之外的平台，例如 GitLab，就没法享受 GitHub Actions 的便利了。因此我们需要在本地构建站点（或者在其他第三方 CI 平台），然后推送站点文件到服务器上。

在项目根目录，运行:

$ JEKYLL_ENV=production bundle exec jekyll b

或者通过 Docker 构建:

$ docker run -it --rm \
    --env JEKYLL_ENV=production \
    --volume="$PWD:/srv/jekyll" \
    jekyll/jekyll \
    jekyll build

生成的静态文件将会在 _site，把内部的文件上传到服务器即可。

文档

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

参与贡献

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

鸣谢

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

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

还有，感谢 JetBrains 提供开源 License！

赞助

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

许可证书

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

8.7 KiB Raw Blame History Unescape Escape