Post

使用 GitHub Pages + Jekyll Chirpy 搭建个人主页

本文介绍使用 GitHub Pages + Jekyll Chirpy 搭建个人主页、进行个性化配置的操作流程和注意事项。

Posted Updated
By Frogman
9 min read
使用 GitHub Pages + Jekyll Chirpy 搭建个人主页

环境

本文采用 Windows 11 + VS Code。

在 Windows 系统上搭建本地调试环境可以使用 Dev Containers，参见 Using Dev Containers (Recommended for Windows)（本文未采用）。

操作流程

参考资料

安装 Ruby

  1. 在 官网 下载最新版 WITH DEVKIT 的 Ruby。

  2. 下载完毕打开 ridk install，在跳出的 CMD 中输入 3（选择“MSYS2 and MINGW development tool chain”），安装 gem 扩展。

安装 Jekyll

  1. 打开 CMD，安装 Jekyll
    1

    gem install jekyll bundler
  2. 查看是否成功安装
    1

    jekyll -v

新建 GitHub 仓库

  1. 有两种选择：
    • 对于新手而言，建议使用 chirpy-starter，优点是更新便捷，缺点是能做的改动较少；
    • 如果对 Jekyll 比较熟悉或希望做较大改动，可以使用 jekyll-theme-chirpy。

    这里介绍前一种。使用前一种时也可以将希望修改的文件从 jekyll-theme-chirpy 中迁移过来进行改动，在生成博客时会覆盖原先 gem 包中的同名文件。

  2. 点击 Use this template，Create a new repository，仓库命名为 username.github.io。注意区分 GitHub 的 name 和 username，如果 username 中有大写则用小写。

  3. 在新建仓库中点击 Settings，在 Pages 中将 Source 修改为 GitHub Action。

  4. 可以将 _config.yml 文件中的 url 改为自己的网址，此时从浏览器进入即可看到原始的网站了。

本地部署和调试

  1. 打开 CMD，到目标目录，从 GitHub 上克隆刚刚创建的仓库到本地。

  2. 打开 VS Code，到该仓库的根目录下，在终端输入
    1

    bundle
  3. 在 VS Code 终端输入
    1

    bundle exec jekyll s

    此时可以看到以下信息，从浏览器进入该网址即可实现本地预览。

    Server address: http://127.0.0.1:4000/

    需要注意的是，本地预览和实际部署效果不完全一致。

网站基本配置

  1. 在 _config.yml 文件中进行配置，包括但不限于：
    • url
    • avatar：侧边栏头像，可选择本地路径或链接。如选择本地路径，将图片放在 assets/img/ 中并在 _config.yml 中填写路径
    • title: 侧边栏名称
    • timezone: 中国输入 Asia/Shanghai
    • 注意 social 下的 links 至少要有一个链接，且注意格式（- https://...）

  2. _data/contact.yml 文件配置网站侧边栏底部诸 contact 按钮，对不想要的可以直接注释掉。

  3. 在 _tabs/about.md 文件中配置 ABOUT 页信息。

部署个人主页

把本地修改 commit 并提交到 GitHub 远程仓库上，可以触发 GitHub Action 的 Build and deployment 工作流进行部署。如果没有自动触发，可以手动点击 Build and Deploy 进行部署。

博客内容个性化配置

Jekyll 在 3.2.0 版本后引入了 gem-based theme，实现了主题样式和博客内容的分离。利用 Chirpy Starter 生成的 blog 只包含内容文件。本节在这样的基础上介绍个性化配置。

自定义网站图标

Chirpy 的图标放在 assets/img/favicons （注意加 s）中。

通过 Real Favicon Generator 生成网站图标（所有选项均可保持默认）。下载生成的包，删除其中的 site.webmanifest 文件，然后将其他文件放置在 assets/img/favicons 目录下即可。

撰写文章

参见 Writing a New Post。

写作语法参见 写作语法示例。

注意

  1. 文件名 YYYY-MM-DD-TITLE.EXTENSION 中的 TITLE 不必与 Front Matter 中的 title 相同，建议采用小写英文加连字符的格式。
  2. Front Matter 中的 title 建议用半角双引号（""）包裹，以防 YAML 解析器对标题中特殊字符（如 :）误解析。
  3. Jekyll/GitHub Pages 的无障碍检查要求每个 <img> 都要有 alt 描述。
  4. Kramdown 是 Jekyll 的默认 Markdown 渲染器。该渲染器默认对每个有序列表都会重新从 1 开始编号，无论 Markdown 中写的是 1.、2. 还是 3.。默认情况下，Jekyll 使用 GitHub Flavored Markdown（GFM）处理器处理 Kramdown。如果希望隔一行的内容被算作第 1 条列表项的一部分，而不是新开一段，从而避免 Kramdown 自动重编号，列表项内的额外段落必须缩进四个空格。
  5. JavaScript 中的单行注释（//）会注释掉该行剩余的所有内容。当 Jekyll-Minifier 将整个HTML文件压缩成单行时，注释会“吞噬”掉函数剩余部分和闭合的下花括号，表现为 Uncaught SyntaxError: Unexpected end of input。建议在 JavaScript 中使用块注释（/* ... */）来避免这个问题。

私密文章

参见 GitHub Pages 私密文章实现。

评论区

可以使用 Disqus、Utterances 或 Giscus 提供的评论系统服务，在 _config.yml_ 文件中的 comments 板块进行配置。本文使用 Disqus。

操作流程

  1. 在 官网 注册 Publishers 账号，然后点击右上角 Settings 选择 Add Disqus To Site，登记站点信息，获取（或设置）站点 Shortname，然后 Create Site。

  2. 完成后点击 Settings 选择 Admin，选择刚刚的站点，点击 Edit Settings，在 General 中编辑 Website URL，在 Ads 中关闭广告，在 Reactions 中可以修改或关闭 Emojis，在 Moderation 中可以设置评论规则。

  3. 在 _config.yml_ 文件中的 comments 板块配置 provider（disqus）和 shortname。

访客统计

参考资料

操作流程

本文使用 Busuanzi 显示访问次数，“两行代码，搞定计数”，在想要显示的地方插入代码即可。

  1. 本站总访问量
    1
2

    <script async src="https://busuanzi.ibruce.info/busuanzi/2.3/busuanzi.pure.mini.js"></script>
<span id="busuanzi_container_site_pv">本站总访问量 <span id="busuanzi_value_site_pv"></span> 次</span>
  2. 本站总访客数
    1
2

    <script async src="https://busuanzi.ibruce.info/busuanzi/2.3/busuanzi.pure.mini.js"></script>
<span id="busuanzi_container_site_uv">本站总访客数 <span id="busuanzi_value_site_uv"></span> 人</span>
  3. 本页总阅读量
    1
2

    <script async src="https://busuanzi.ibruce.info/busuanzi/2.3/busuanzi.pure.mini.js"></script>
<span id="busuanzi_container_page_pv">本页总阅读量 <span id="busuanzi_value_page_pv"></span> 次</span>

注意

  1. 如果使用 127.0.0.1:4000 进行本地预览，由于域名不是我们的真实域名（username.github.io），Busuanzi 给出的站点总访问量和总访客数不正确。

  2. 很多静态博客都使用 Busuanzi 进行访客统计，因此其存在响应速度慢的问题。可以考虑自己搭建 Busuanzi 服务，参见上面的资料。也可以像本站 ABOUT 页面 中展示的那样使用 Moe Counter 进行页面浏览数的统计，有很多效果可供选择。

其他装饰效果

推荐阅读 GitHub主页Profile装饰指南。

主题样式个性化配置

推荐阅读 Chirpy Blog Customization。

Everyone is welcome to reach out and exchange ideas.

Please credit the source as Frogman's Blog (https://frogmanr9.github.io) and include the link to this article (https://frogmanr9.github.io/posts/githubpages-jekyll-chirpy/). Thank you.

This page has views.

Web
jekyll manuals
This post is licensed under CC BY 4.0 by the author.