Jekyll + Github Pages搭建文档

李安歌

2023-12-01

__posts 博客内容
_pages 其他需要生成的网页，如About页
_layouts 网页排版模板
_includes 被模板包含的HTML片段，可在_config.yml中修改位置
assets 辅助资源 css布局 js脚本图片等
_data 动态数据
_sites 最终生成的静态网页
_config.yml 网站的一些配置信息
index.html 网站的入口

2. 关于布局

以首页为例，打开根目录下的index.html（网站首页）可以看到：

—

layout: articles

—

html代码段

上面的articles就是_layouts\articles.html，布局中又可以通过如下方式就像调用函数一样调用_includes下的html片段

{%- include article-list.html articles=_articles type=‘grid’ -%}

注：其他页面的布局设置为_config.yml中的defauls/values/layout

3.更进一步

如果想更详细的了解Jekyll，可以访问：

本篇文章主要内容

Jekyll含有多种主题，本篇文章讲述以TeXt Theme为基础，进行的修改和增加的功能，包括

使用collection
配置侧边栏
优化前后页按钮
添加代码块一键复制功能
更改Logo和Favion
修改字体高亮颜色和大小

1. 使用collection

1.1 为什么要使用collection

Jekyll发布文章，所需要做的就是在/_posts文件夹中创建一个新的文件。但是这种方式要求文件名遵循下面的格式:年-月-日-标题.md，这种方式写博客的话自然是没有问题你的，但对于不是博客的内容，这种命名格式就显得没有必要了。

1.2如何使用collection

1.2.1 告诉Jekyll读取你的collection

将以下内容添加到你的网站的_config.yml文件中：

collections_dir: my_collections # 选择指定一个目录来将所有合集存储在同一个位置
collections:
  my_collection: # 你的collection名称
    output: true #渲染合集中的每个文档

1.2.2 添加内容

在根目录下创建my_collections文件夹，然后在其下创建_my_collection文件夹，注意文件夹名要以_开头，所以你的collection名称不能以_开头，然后在这个文件夹下添加markdown文件，访问 http://localhost:4000/python-sdk/文件名.html 预览网页效果。

collection更详细的内容见：《Jekyll使用教程笔记五：合集、数据文件》

2. 配置左侧边栏

侧边栏的具体使用方法在快速开始中已经说明，但是TeXt的侧边栏默认是只支持到二级目录，那么如果侧边栏需要三级目录该怎么做呢？相关文件为_includes\sidebar\toc.html，以下为核心代码：

      {%- for _item in _sidebar_nav -%}
        <li class="toc-h1">{{ _item.title }}</li>
        {%- if _item.children -%}
          {%- for _child in _item.children -%}
			<!-- 二级目录 -->
            {%- include snippets/get-nav-url.html path=_child.url -%}
            {%- assign _nav_url = __return -%}
            {%- include snippets/get-nav-url.html path=page.url -%}
            {%- assign _page_url = __return -%}
            {%- if _nav_url == _page_url -%}
              <li class="toc-h2 active"><a href="{{ _nav_url }}">{{ _child.title }}</a></li>
            {%- else -%}
              <li class="toc-h2"><a href="{{ _nav_url }}">{{ _child.title }}</a></li>

上面就是Jekyll使用的Liquid模板语言，并不复杂，可以看出，这段代码就是读取我们在_data/navigation.yml中定义的侧边栏，具体的逻辑为：

先取定义的item的titile作为一层目录，然后如果有children属性就读取相应的title和url作为二级目录，如果该目录为当前页面，就高亮显示。

因此，要添加三级目录的话，我们只要模仿这个循环再做一层遍历就可以了。

添加如下代码：

            <!-- 三级目录 -->
			{%- if _child.children -%}
              {%- for __child in _child.children -%}
                {%- if __child.title == page.title -%}
                  <li class="toc-h3 active"><a href="{{ __child.url }}">{{ __child.title }}</a></li>
                {%- else -%}
                  <li class="toc-h3"><a href="{{ __child.url }}">{{ __child.title }}</a></li>

这里有两点要注意：

二级目录是可能不存在url的，所以要进行判断。
原代码判断当前代码的依据是url，原来的url会包含日期和\，而我们使用了collection，url是不包含日期的，因此这个判断会失效。所以我将判断依据改为title。

以下为修改过的二级目录代码。

      {%- for _item in _sidebar_nav -%}
        <li class="toc-h1">{{ _item.title }}</li>
        <!-- 二级目录 -->
        {%- if _item.children -%}
          {%- for _child in _item.children -%}
          <!-- 根据是否为当前页面判断要高亮 -->
            {%- if _child.title == page.title -%}
              {%- unless _child.url  -%}
                <li class="toc-h2 active">{{ _child.title }}</a></li>
              {%- else -%}
                <li class="toc-h2 active"><a href="{{ _child.url }}">{{ _child.title }}</a></li>
              {%- endunless -%}
            {%- else -%}
            <!-- 判断二级目录是否有url属性 -->
              {%- if _child.url == null -%}
                <li class="toc-h2">{{ _child.title }}</a></li>
              {%- else -%}
                <li class="toc-h2"><a href="{{ _child.url }}">{{ _child.title }}</a></li>

注：这篇文章只会附带核心代码，具体的不同可以比较我的代码和TeXt Theme的原始代码

3.优化前后页按钮

相关文件为_includes\article-section-navigator.html，代码逻辑为判断当前页是否存在前后页，然后生成前后页按钮。具体逻辑如下：

遍历侧边栏，先找到侧边栏中属于当前页面的一项，然后有下一项的话就是下一页，找到之前不断记录当前项为前一页。

其中和配置侧边栏一样，在判断项是否为当前页时也涉及到了url，所以会出问题，也要用改为比较title，然后，增加处理第三层目录的逻辑。

具体代码太长，不贴出来了。

4. 添加代码块一键复制功能

有人给TeXt贡献了相关的分支，详情见为博客添加代码块一键复制功能

5. 更改Logo和Favion

具体的更改，TeXt的文档中心有相关说明：Logo和Favion

做两点补充

Logo:jpg转svg可用jpg-to-svg
Favicon：博客中的最后一步 “将 HTML 代码替换到_includes/head/favicon.html 文件中”，不需要执行，执行的话会报路径错误。如因图片尺寸或其他原因不得不修改的话，请注意保持路径的一致性。

6. 修改字体高亮颜色和大小

文本高亮颜色：修改_sass\skins\_default.scss中的$main-color-1
代码高亮字体大小：找到 _sass\common_reset.scss，将里面 code 中 font-size-sm 改成 font-size
修改左侧侧边栏字体大小：找到_sass\common\components\_toc.scss，修改ul.toc--navigator中的.toc-h1(一级目录）中的font-size
修改右侧侧边栏字体大小：找到_sass\common\components\_toc.scss，在ul.toc--ellipsis下仿照ul.toc--navigator 增加.toc-h1等项，并设置其中的font-size
去除右侧侧边栏目录范围限制：去除_sass\common\components\_toc.scss中的& > li，

Jekyll + Github Pages搭建文档

目录

Jekyll 和 Github Pages是什么？

Jekyll 基础

1. Jekyll 目录结构