Skip to content

博客共享侧边栏实现原理

一、场景说明

当前博客有大量文章,许多文章的左侧共享一个侧边栏。如果一个文件更新了,需要重新构建所有文章页面,这样会导致构建速度非常慢。所以需要一种方式,只重新构建该文件的页面,而不是所有文件。

当前实现是:构建完整文章页面,但把页面中的左侧导航替换为占位区域;浏览器打开页面后,再加载当前栏目共享的导航片段。

文章页面仍然包含顶部栏目、正文、右侧文章目录、样式和脚本引用等内容。只有原先重复嵌入的完整左侧导航被抽离。

二、问题一:一个网页怎么加载两部分 HTML?

2.1 浏览器显示的是 DOM 树

浏览器收到 HTML 后,会把它解析成 DOM 树。页面显示出来以后,JavaScript 仍然可以往这棵树里添加节点。新加入的节点与原有正文参与同一个页面的布局,并使用页面里已经加载的 CSS。

文章页面最初可以理解为下面的结构。这是说明原理的简化代码,不是项目模板的完整内容:

<body>
  <header>顶部栏目</header>

  <aside id="sidebar">
    加载栏目目录…
  </aside>

  <main>
    <h1>文章标题</h1>
    <p>文章正文……</p>
  </main>
</body>

2.2 脚本生成专门的侧边栏文件

正如开头所说的,许多文件的左侧共享一个侧边栏。所以脚本会生成专门的侧边栏文件,如下图所示。

侧边栏 HTML 文件

每个文件名后面那么多数字和字母,其实是根据内容计算的哈希,只要保证唯一性即可。把文件里面的代码替换到上面的 sidebar 区域即可。

2.3 JavaScript 请求导航片段并插入页面

请求侧边栏的方式

页面脚本发起另一次 HTTP 请求,取得当前栏目公共导航文件的文本,然后将它插入侧边栏区域:

// 示意代码
const response = await fetch("/navigation/shared/group-3-012345abcdef.html");
const html = await response.text();
document.querySelector("#sidebar").innerHTML = html;

返回的就是是 HTML 片段,赋值给 innerHTML 后,浏览器将这段文本解析成节点,放入现有页面。

如何知道请求哪一个

上面请求是如何知道要请求哪个侧边栏呢,其实在每个页面中都写好了:

<div
  data-shared-navigation="../../navigation/shared/group-3-012345abcdef.html"
  data-site-root="../../"
  aria-busy="true">
  <a href="../../">占位区域,请求成功,这一整行会被替换为导航节点…</a>
</div>

其中:

属性 用途
data-shared-navigation 目录 HTML 的地址,相对于当前页面解析
data-site-root 站点根目录,用来解析共享目录内部的链接和图片地址
aria-busy 表示目录是否仍在加载;加载结束或失败后设为 false

解析站点地址

上面请求是用的相对总地址的请求,所以需要一开始先解析站点地址:

var root = new URL(
  container.dataset.siteRoot,
  window.location.href
);

举例子:

new URL(
  "../../../",
  "http://127.0.0.1:8000/Language/CPP/cpp_constexpr/"
);
// 得到:http://127.0.0.1:8000/

new URL("Language/Python/", root).href;
// 得到:http://127.0.0.1:8000/Language/Python/

完整过程如下:

打开文章地址
    ↓
取得完整文章 HTML:正文 + 页面框架 + 导航占位区域
    ↓
执行页面 JavaScript
    ↓
请求所属栏目的公共导航片段
    ↓
将导航节点插入占位区域
    ↓
根据当前文章地址设置高亮、展开父目录

因此,最终只有一个页面、一棵 DOM 树。文章内容来自首次请求,导航片段来自后续请求。

2.3 高亮部分处理

侧边栏会高亮当前文章,所以如果不做处理,这部分会有问题。

插入导航后,脚本比较当前页面 URL 与导航链接,给匹配文章设置高亮和 aria-current="page",再展开它的父目录。这样,同一份 Language 导航既可以用于 Python 文章,也可以用于 CPP 文章。

三、问题二:没有命令选项,怎么拆开侧边栏?

3.1 侧边栏由主题模板决定

构建命令负责组织构建过程,而页面里哪些位置输出什么 HTML,由主题模板决定。因此,拆分左侧导航不要求命令行提供专门选项。

原先的模板逻辑可以简化为:

<aside>
  {% include "partials/nav.html" %}
</aside>

<main>
  {{ page.content }}
</main>

构建每篇文章时,partials/nav.html 会展开导航树,产生导航 HTML。结果就是很多文章页面重复保存相同目录。

3.2 覆盖模板,改成输出占位区域

项目已有自定义主题模板目录。我们在 overrides/base.html 中,将左侧导航的引用改为:

{% include "partials/shared-nav.html" %}

新的 shared-nav.html 先判断文章所属的顶部栏目,再通过生成的清单取得该栏目的公共导航路径。它的实际输出结构是:

<div data-shared-navigation="{{ shared.path(selected.index) | url }}"
     data-site-root="{{ base_url }}/"
     aria-busy="true">
  <a href="{{ '.' | url }}">加载栏目目录…</a>
</div>

其中:

  • data-shared-navigation:当前栏目导航片段的地址。
  • data-site-root:用于解析片段内链接的站点根地址。
  • aria-busy:表示目录仍在加载。

这里不再展开整棵左侧导航,但正文和页面其他部分仍然按原来的模板流程生成。

四、文件更新与浏览器缓存如何处理?

公共导航文件名带有根据内容计算的哈希,实际名称类似:

navigation/shared/group-6-48ff05914319.html

只修改文章正文时,导航结构不变,公共导航文件也不需要变化。同栏目文章引用相同地址,浏览器可以按照 HTTP 缓存规则复用已有响应;是否重新请求,还取决于服务端缓存头和浏览器设置。

调整某个栏目目录后,导航内容改变,生成器会计算新的文件名。重新构建的文章页面引用新地址,浏览器便会获取新的导航片段。

五、解决结果

以前每篇文章 HTML 都携带大量重复导航。抽离后,构建产物中的 HTML 总量从约 817 MiB 降到 84 MiB。这是此前两次产物统计的结果,主要收益来自减少重复导航。

六、对应源码位置

以下为维护时应修改的源码位置,生成目录中的文件会被后续构建覆盖。

文件 用途
D:\Blog\scripts\web\generate_shared_navigation.py 生成公共导航片段和路径清单
D:\Blog\scripts\web\overrides\base.html 完整页面模板,引用共享导航占位模板
D:\Blog\scripts\web\overrides\partials\shared-nav.html 按当前顶部栏目输出导航地址与占位区域
D:\Blog\scripts\web\overrides\javascripts\shared-navigation.js 请求片段、插入 DOM、设置当前文章状态
D:\Blog\scripts\web\live_preview.py 启动本地快速预览时生成共享导航
D:\Blog\scripts\web\mkdocs-phone.yml 本地/手机版配置,加载导航脚本
D:\Blog\scripts\web\mkdocs-web.yml 网页版配置,加载导航脚本

Comments

本文阅读 Loading 次 本站访问 Loading 次 访客 Loading 人