本地服务挂载原始资源
使用对原始文件进行转换再去挂载的逻辑,有一个好处,就是可以根据不同的任务情况,实现不同的转换结果,这样只需要维护一个原始文件,但最终用在不同的场景中。
本文就是说明了这样一个场景:我一般会有一个本地服务,用的全是本地已有的资源,没有外部的请求。比如字体是提前下载好的、取消站点统计等等,这样浏览器打开和切换文章很快,基本是无感的。
而很自然地,本地服务不会像公开站点一样,有大资源限制,他是可以查看任何如视频文件这种大资源的。但是这就导致一个问题:我不可能像公开站点那样,把资源再复制一份到 docs/asset 目录中,因为大资源最后统计出来大小很大。正确做法是直接挂载原始资源。本文就是讲的实现这样一个需求。
1. 先理解三个结论
- 共用的是中间 Markdown,公开站点与本地站点分别生成 HTML。 公开 HTML 可以显示“未在线发布”,本地 HTML 可以在同一位置显示播放器或 PDF 阅读框。
- 资源网址不等于磁盘文件位置。 本地服务收到
/asset/...请求后,可以查表读取done/中的原文件,不要求站点输出目录中存在一份同名副本。 - 文件转换、资源复制、网页展示是三个独立步骤。 Word/PPT 可以先生成本地 PDF 缓存,再决定是否复制进发布目录;视频可以直接读取原文件,无须转换或复制。
这一机制主要解决超限资源和独立视频的本地使用问题。普通小图片、小 PDF 等资源仍可沿用原来的复制发布流程。
2. 整体结构
原始内容:D:\Blog\done\
│
│ 转换、链接处理、资源登记
▼
共享中间文件:D:\BlogSite\masterAllen.github.io\docs\
│
├─ 普通正文、普通资源链接
└─ 本地资源标记 + resource_cards 元数据
│
│ Zensical 根据不同构建配置渲染主题模板
├──────────────────────────┐
▼ ▼
公开 HTML 本地 HTML
local_resources: false local_resources: true
│ │
显示未发布说明 显示播放器、图片或 PDF 阅读框
不生成该卡片的资源请求链接 浏览器请求本地 /asset/... 地址
│
▼
本地资源服务查登记表
│
┌───────────┴────────────┐
▼ ▼
读取 done/ 原文件 读取 .resource-cache/ PDF
│ │
└───────────┬────────────┘
▼
返回文件内容给浏览器
关键:中间生产的 Markdown 是共用的,条件判断发生在主题模板渲染 HTML 时。
3. 转中间 Markdown
3.1 本地资源登记表
转换的时候会维护一个本地资源登记表,位置为:
D:\Blog\scripts\web\configs\local_resources.json
里面包含了许多条目,记录了本地资源,比如:
{
"8e59c60ed849360b8e104a04de0384b7": {
"source": "D:\\Blog\\done\\系统性知识\\Computer-Network\\00.Network_Judge\\demo.mp4",
"conversion": null,
"kind": "video",
"name": "demo.mp4",
"url": "/asset/video/9f31d4a0058ae150ec42806b529c99b2/demo.mp4",
"fragment": "",
"style": "",
"bytes": 65602125
},
}
字段含义:
| 字段 | 含义 |
|---|---|
KEY |
卡片 ID |
source |
本地服务实际读取的源文件,或本地 PDF 缓存文件 |
conversion |
是否需要请求时转换;普通资源为 null,大 Office 原文件为 word 或 ppt |
kind |
最终展示类型,例如 video、image、pdf、html |
name |
展示名称 |
url |
未进行 URL 百分号编码的逻辑资源路径 |
fragment |
需要保留的 URL 后缀,例如图片的 #w65 |
style |
从相应 HTML 元素提取的样式,例如已有的 zoom |
bytes |
登记时对应源文件的大小 |
需要注意 local_resource.json 只记录那些需要特别处理的文件,普通一些小图片之类的,还是会按照原来的逻辑处理。不然这个文件最后会非常大,每次重新写会很麻烦。
3.2 中间 Markdown 的资源元数据
转中间 Markdown 时保存渲染需要的信息,不保存登记表中的 source 和 conversion 字段:
---
comments: true
hide:
- toc
resource_cards:
- id: 8e59c60ed849360b8e104a04de0384b7
marker: '<!--blog-resource:8e59c60ed849360b8e104a04de0384b7-->'
url: /asset/video/9f31d4a0058ae150ec42806b529c99b2/demo.mp4
kind: video
name: demo.mp4
megabytes: '62.56'
fragment: ''
style: ''
- id: 8fe0d22925eff941df89f5a76a6f8185
marker: '<!--blog-resource:8fe0d22925eff941df89f5a76a6f8185-->'
url: /asset/html/76885b19a4c5c21bca97e07a1ece4840/demo.html
kind: html
name: demo.html
megabytes: '47.91'
fragment: ''
style: ''
---
每个 id 对于文章的一个资源引用。这里的 marker 表示正文中的资源引用标记。比如转换后的 markdown 中内容为:
下面是视频:
<!--blog-resource:8e59c60ed849360b8e104a04de0384b7-->
下面是 HTML 演示:
<!--blog-resource:8fe0d22925eff941df89f5a76a6f8185-->
后续转 HTML 的时候,会有不同的行为(见下个章节),公开构建的网站如下:
下面是视频:
demo.mp4:此资源未在线发布
下面是 HTML 演示:
demo.html:此资源未在线发布
本地构建的网站如下:
下面是视频:
[播放器]
下面是 HTML 演示:
[HTML 阅读框]
resource_files.add_metadata() 负责这个功能,它会扫描正文标记,从登记表提取相应记录,将所需字段写入 resource_cards。
4. 共用 Markdown 如何生成不同 HTML
4.1 构建配置说明
之所以能生成不同 HTML,是因为构建配置不同。
公开配置和本地配置的关键就在于,这个 local_resources 的值不同。
extra:
local_resources: false
Mkdocs/Zensical 转换的时候可以利用这些配置来生成不同的 HTML。比如核心条件可以简化理解为(简化理解,后面会详细解释实际逻辑):
{% if config.extra.local_resources %}
<!-- 根据资源类型生成本地预览与链接 -->
{% else %}
<!-- 生成未在线发布说明 -->
{% endif %}
4.2 模板渲染顺序
Zensical 将 Markdown 转为 page.content
↓
base.html 检查 page.meta.resource_cards(也就是 5.2 节所说的文章开头保存的信息)
↓
有资源卡片时使用 resource-content.html(见下文 6.3 节)
↓
逐个读取资源元数据,每个数据使用 resource-card.html 生成卡片 HTML(见下文 6.4 节)
↓
将 page.content 中对应注释标记替换为卡片 HTML
4.3 统筹替换逻辑
resource-content.html 是我们新增的主题模板片段,负责统筹处理把正文里的标记替换成资源卡片 HTML。
{% set rendered = namespace(content=page.content) %}
{% for resource in page.meta.resource_cards | d([]) %}
{% set card %}
{% include "partials/resource-card.html" %}
{% endset %}
{% set rendered.content = rendered.content | replace(resource.marker, card) %}
{% endfor %}
{{ rendered.content | safe }}
它的工作过程是:
- 取得当前文章的正文
page.content。 - 遍历文章的
resource_cards列表。 - 为每个资源生成卡片 HTML。
- 找到正文中对应的
marker,替换成这张卡片。 - 输出替换后的正文。
4.4 单文件替换逻辑
resource-card.html 负责生成单个资源卡片 HTML,他会来判断是公开还是本地预览。然后根据判断结果生成不同的 HTML。
<span class="blog-resource">
{% if config.extra.local_resources %}
{# 这里生成本地播放器、图片或 PDF 阅读框 #}
{% else %}
<span>
{{ resource.name }} · {{ resource.megabytes }} MB:
此资源未在线发布,可在本地服务中查看。
</span>
{% endif %}
</span>
所以最终调用关系是:
base.html
→ resource-content.html:遍历资源,替换正文标记
→ resource-card.html:判断配置,生成每张卡片;这里公开站点和本地站点就会有不同内容
5. 两种本地服务的读取方式
本地挂载 http 服务,用于访问站点,启动入口:
python -X utf8 D:\Blog\scripts\web\serve_local_site.py
这里的 URL 有两种类型,一种是文章页面,一种是资源请求:
http://127.0.0.1:8000/系统性知识/
http://127.0.0.1:8000/asset/video/<哈希>/demo.mp4
脚本里面会判断 URL 类型,他会注册 /asset/ 资源路由:
def handlers(fallback_root=None):
return [
(
r'/asset/(.*)',
ResourceHandler,
{
'path': settings.srcdir,
'fallback_root': fallback_root,
},
),
]
其中 r'/asset/(.*)' 表示:匹配 /asset/ 开头的请求,交给 ResourceHandler。而后续就是去查找本地登记表,看看是否有这个哈希,如果没有就回退读取 asset 中已有的普通静态资源。
本地登记表会维护一个 url_to_value 的查找表,所以查找速度是 O(1),很快:
# 登记表加载或变化时,建立一次索引
resources_by_url = {
item['url']: item
for item in registry.values()
}
# 每次请求直接查找
record = resources_by_url.get(url)
这里为什么不直接用 http://127.0.0.1:8000/asset/video/<哈希> 这种形式?
如果这里的哈希是 KEYID,那么这样直接是 O(1) 复杂度,查找很快。
但这个会带来一些问题,最最主要的是缩放图片时比较麻烦。假设原文中同一图片出现两次:


当前卡片 ID 的计算包含宽度后缀,因此两处的 ID 不同,可以简称为 A、B。
旧 URL 是:
/asset/image/目录哈希/large.png#w50
/asset/image/目录哈希/large.png#w65
图片缩放功能去掉 #w50、#w65 后,两个地址相同,于是知道:这是同一原图出现了两次,第二张对应原文中的第二次引用。
改成 KEYID 地址后:
/asset/image/A#w50
/asset/image/B#w65
去掉宽度后,地址仍然不同。原来的前端分组逻辑会把它们当成两张不同图片,只把选中的一张发给编辑接口;而接口从原文中找到的是两次引用。数量对不上,就会拒绝。
可以处理,但是这样太过麻烦了。所以使用直接查找 url 的方式,而且也是维护一个查找表,无非内存多用一点而已了。
细节
-
例如,一份 PDF 以前只有 5 MB,允许发布;后来变成 20 MB,转为本地专用时,需要删除之前的发布副本。转换过程会处理一下这种情况。
-
本地文件名有很多不好的字符,比如空格、百分号等等等,所以转
url会在生成元数据时进行百分号编码。