title: date: 2026-04-24

从 2022 年自己搭建博客至今，中间折腾了不少东西，框架换来换去，记录在这里 博客再改版 但是没有一个让我自己最满意的。而为了写个博客去学习它的模板语法、配置方式，感觉很麻烦，一直都想自己写一个，直到最近才抽空用 copilot 写了一个基于 python 的框架，核心代码就几百行，不依赖任何外部库，自己控制所有逻辑，想咋样就咋样，出问题也知道去哪修。

这个博客框架有以下几个我比较喜欢的特性：

短链

_slug_hash 函数根据每个文章的文件夹名称，使用 CRC24 哈希并通过 base36 输出 5 位全小写短链，直接映射到主域名下面，比如 https://jiaoyuan.org/5xbok/，既干净又便于分享，也不会产生冲突。

BASE62 = "0123456789abcdefghijklmnopqrstuvwxyz"
RESERVED_SLUGS = frozenset({"assets", "logs", "readme", "page", "atom", "posts"})

def _crc24(data: bytes) -> int:
    crc = 0xB704CE
    for b in data:
        crc ^= b << 16
        for _ in range(8):
            crc <<= 1
            if crc & 0x1000000:
                crc ^= 0x1864CFB
    return crc & 0xFFFFFF

def _slug_hash(name: str) -> str:
    val = _crc24(name.encode())
    result = []
    while val > 0:
        result.append(BASE62[val % len(BASE62)])
        val //= len(BASE62)
    return "".join(reversed(result)).rjust(5, "0")

load_posts 读取文章时自动计算短链，并且通过 used 集合做唯一性检查，撞了自动加后缀：

def load_posts(cfg, engine):
    used = set()
    for folder in sorted(posts_dir.iterdir()):
        slug = _slug_hash(folder.name)
        if slug in used or slug in RESERVED_SLUGS:
            i = 1
            while f"{slug}-{i}" in used:
                i += 1
            slug = f"{slug}-{i}"
        used.add(slug)

渲染优化

现在很多博客框架我觉得都太复杂，为了适应大多数人的要求，加入了很多冗余的功能，我这里想办法减少了前端渲染和 js 的加载。Markdown 的渲染是自己写的，没有用任何现有的解析器。支持的语法包括标题、段落、列表、引用、表格、代码块、行内样式这些常用功能，日常写文章完全够用。

代码块这里支持 bash 、python 、c 、r 、html 、css 、c# 这些语言的语法高亮，由 _highlight_source 方法在构建时即直接渲染为带 token 类名的 HTML 标签，不加载任何 JS ，速度快了很多，并且适配暗色和亮色模式。

def _highlight_source(self, code: str, lang: str) -> str:
    kw = {"python": {"def", "class", "if", "else", "for", ...}, ...}
    token_re = re.compile(
        r"(?P<comment>#..."
        r")|(?P<string>\"...\")"
        r"|(?P<keyword>\b...\b)"
        r"|(?P<number>\b\d+\.?\d+\b)"
    )
    for m in token_re.finditer(code):
        if m.lastgroup == "keyword":
            out.append(f'<span class="tok-k">{text}</span>')
        elif m.lastgroup == "string":
            out.append(f'<span class="tok-s">{text}</span>')

CSS 变量根据主题切换，无需额外 JS 处理高亮颜色：

:root {
  --tok-k: #0550ae; /* keyword */
  --tok-s: #0a3069; /* string */
  --tok-c: #6e7781; /* comment */
}
[data-theme="dark"] {
  --tok-k: #79c0ff;
  --tok-s: #a5d6ff;
  --tok-c: #8b949e;
}

页面生成后直接写静态 HTML 文件，Nginx 直出，不需要任何后端处理或数据库查询：

def _write(public_dir: Path, rel_out_dir: str, html_text: str) -> None:
    out = public_dir / rel_out_dir
    out.mkdir(parents=True, exist_ok=True)
    (out / "index.html").write_text(html_text, encoding="utf-8")

数学公式渲染用的 KaTeX ，通过正则检测文中是否包含 $...$ 或 $$...$$ 或者 front matter 是否声明 math: true，只有在需要的时候才加载 KaTeX 的 CSS 和 JS：

MATH_RE = re.compile(r"\$\$.*?\$\$|\$[^$\n]+\$", re.DOTALL)

def _load_markdown_file(path, rel_url, out_dir, is_log, engine):
    body = ...
    has_math = bool(MATH_RE.search(body)) or bool(meta.get("math"))
    return ContentItem(has_math=has_math, ...)

评论系统

评论基于 GitHub Issues 。每篇文章底部有一个按钮，默认链接到新建 issue 页面，标题已经预填好。同时页面加载后会通过 GitHub API 搜索匹配该标题的现有 issue ，如果找到就直接把按钮链接跳转过去，不需要建一堆重复的讨论。

# config 里配置评论仓库
cf = {"comment_repo": "imjiaoyuan/imjiaoyuan.github.io"}

# 渲染评论区域
btn = f'<a href="https://github.com/{repo}/issues/new?title={title}">...</a>'

# 加载后自动匹配已有 issue
fetch("https://api.github.com/search/issues?q=" + q)
  .then(r => r.json())
  .then(data => {
    if (data.total_count > 0) btn.href = data.items[0].html_url
  })

不用额外注册任何第三方评论服务，仓库的 Issues 就是数据库。

整个博客就一个 GitHub 仓库，内容、源码、生成的静态文件都在里面。提交后 GitHub Actions 会自动执行构建，生成 HTML 然后部署到 Pages 。整个过程全自动，不用手动敲命令，也不用登录什么后台。本地构建的时候可以使用 run.py，其包含三个命令：

python run.py -d            # 构建静态站点到 public/
python run.py -s            # 构建并启动开发服务器（热重载）
python run.py -n post-name  # 创建新文章

写博客对我来说就是一种记录，把脑子里的东西倒出来整理一下。很多东西不记下来很快就忘了，写下来还能回头看看当时的自己是怎么想的，也挺有意思。