# Writing my own static site generator # 编写我自己的静态网站生成器 2026-01-16 — 2026-01-21 ([Programming/编程](/tags/programming/)) In principle, a static site generator is a good idea: They automatically populate your homepage, index pages and RSS feeds, making it impossible to forget anything. 原则上，使用静态网站生成器（Static Site Generator）是个好主意：它们能自动填充主页、索引页和 RSS 订阅源，让你不会遗漏任何东西。 Unlike a CMS like Wordpress, they don't add runtime cost or security vulnerabilities: They run once to generate your site and are never exposed to the internet. 不像 WordPress 这类内容管理系统（CMS），它们不会增加运行时的开销或带来安全漏洞：它们只需要运行一次来生成站点，而且程序本身永远不会暴露在互联网上。 However, they all put weird restrictions on how you structure your site: 然而，它们都会对你的网站结构施加奇怪的限制： Nearly all of them require you to write in Markdown, which is common, but poorly specified and difficult to parse. As soon as you do anything more complex then bolding a few words, it becomes a struggle to get the parser to do the right thing. 几乎所有的生成器都要求你使用 Markdown 写作。虽然 Markdown 很常见，但它的规范很糟糕，解析起来也很困难。一旦你想做点比“加粗几个字”更复杂的事情，就得费劲地让解析器按你的意图工作。 I recently spent way too much time trying to figure out how to stop it from link-ifying something that looked like a URL. 最近我花了太多的时间去研究怎么阻止它把一段看起来像 URL 的文字自动转成链接。 In any case, the whole thing seems pointless: I'm writing a [website](/tutorials/website), something that will be published exclusively on the web... so... 无论如何，整件事看起来都很没意义：我正在写一个[网站](/tutorials/website)，一个专门发布在 Web 上的东西……所以…… # Why not just use HTML? # 为什么不直接用 HTML？ Converting from Markdown would make sense if HTML was super ugly, but it's not. Here's what bolding looks like in Markdown: 如果 HTML 丑爆了，那从 Markdown 转换过来还有点道理，但 HTML 其实并不丑。这是 Markdown 里加粗的样子： ```markdown This is an **important point** ``` ... and here's the same in HTML: ……这是 HTML 里同样的操作： ```html This is an important point ``` That might be harder to type on a phone keyboard, but if you're writing on a phone, you're not having a good time anyway. 在手机键盘上打 HTML 可能确实难一点，但如果你是在手机上写代码/文章，你的体验本来也好不到哪去。 There are some things that suck with HTML, like manual syntax highlighting, but that sucks in any language. Adding a whole markdown parser just to improve code blocks is overkill. HTML 确实有些地方很烦人，比如手动的语法高亮，但无论用什么语言这都很烦。仅仅为了优化代码块的显示就引入整套 Markdown 解析器，未免有些大材小用。 These translation layers are fragile: The [original website](https://info.cern.ch/hypertext/WWW/TheProject.html) still renders fine in modern browsers, but there's no shortage of Wordpress blogs where all the formatting broke after a server update... and not just a [Wordpress problem](https://madebynathan.com/posts/2021-12-05-how-docker-saved-my-blog/). 这些“翻译层”是很脆弱的：万维网的[初代网页](https://info.cern.ch/hypertext/WWW/TheProject.html)在现代浏览器里依然渲染得很好，但不缺那种因为服务器更新导致格式全乱套的 WordPress 博客……而且这不仅仅是 [WordPress 的问题](https://madebynathan.com/posts/2021-12-05-how-docker-saved-my-blog/)。 # Configuration # 配置 The Markdown thing is somewhat justifiable: A lot of people are more comfortable with markdown then HTML. 非要用 Markdown 多少还算情有可原：相比 HTML，确实很多人对 Markdown 感到更自在。 ... but they all use weird template formats, which are really entire programming languages shoved inside HTML: complete with questionable design decisions and without nearly enough documentation. As a result, it's very difficult to get these tools to do what you want: ……但它们都使用奇怪的模板格式，这实际上就是硬塞进 HTML 里的一整套编程语言：充斥着值得商榷的设计决策，而且文档还严重不足。结果就是，想让这些工具按你的想法工作非常困难： I knew that something as simple as removing the publication date from pages that shouldn't have one (like the [archives](/archive)) would result in hours of googling cryptic error messages. 我很清楚，哪怕是像“从不该显示日期的页面（比如[归档页](/archive)）移除发布日期”这么简单的事，都会导致我花几个小时去谷歌搜索那些晦涩难懂的错误信息。 Using them doesn't feel like handcrafting a personal website. It feels like throwing arcane bullshit at the wall and seeing what sticks. 使用它们感觉不像是亲手打造一个个人网站，倒像是往墙上扔一堆神秘的垃圾，看看哪块能粘住。 # I'll just do it myself # 我决定自己动手 Each article on my site is an HTML file prefixed with a metadata block: 我网站上的每篇文章都是一个 HTML 文件，开头带有一个元数据块： ```text title Example page: date 2021-02-11 edited 2025-01-21 tag electronics tag radiation --- Paragraph one. . Paragraph two . ... the rest of the page ``` My program copies all files from the source tree into the destination directory. Everything except HTML is left unchanged. 我的程序会将源目录树下的所有文件复制到目标目录。除了 HTML 文件外，其他所有内容保持不变。 When it sees an HTML file: The metadata block is parsed and saved for later. Everything else is added to a template with the navigation bar and [styles](/misc/inline_css/) and written to the output directory. 当遇到 HTML 文件时：元数据块会被解析并保存以备后用。其余内容会被添加到一个包含导航栏和[样式](/misc/inline_css/)的模板中，然后写入输出目录。 To make writing easier, the generator supports using a dot on it's own line: 为了让写作更轻松，生成器支持将单独占一行的点号（`.`）： ```text . ``` ... as a shorthand for paragraph breaks: ……作为段落换行的简写： ```html

``` During this process, the generator also saves everything before the `` comment as an excerpt for the homepage. This manual because a good excerpt should be long enough get an idea of what the post is about... but not any longer. 在此过程中，生成器还会保存 `` 注释之前的所有内容，作为主页显示的摘要。这是手动的，因为一个好的摘要应该足够长，让人了解文章的大意……但又不能太长。 Once done with the content, all the posts are sorted by date in reverse order: The first 5 are added to the [homepage](/). The first 20 are included in the [the RSS feed](/index.xml). All posts except space photos are included in the [archive](/archive/) page. All [12 tags](/tags/) get their own index pages. 内容处理完后，所有文章按日期倒序排列：前 5 篇添加到[主页](/)。前 20 篇包含在 [RSS 订阅](/index.xml)中。除了太空照片外的所有文章都包含在[归档](/archive/)页中。所有的 [12 个标签](/tags/)都有自己的索引页。 There's also my [catalog page](/astro/catalog.html) which is generated from objects tagged in photos I've taken: The index page has a section for each astronomical catalog (i.e. NGC), with links sorted by their number in that catalog. (i.e. 5194) Images of the same object are grouped together, and sorted by date taken. Everything shoulds to be on one page for easy searching and browsing. 还有我的[目录页](/astro/catalog.html)，它是根据我拍摄的照片中标记的天体生成的：索引页为每个天文目录（如 NGC）设有一个版块，链接按其在该目录中的编号（如 5194）排序。同一天体的图像被归为一组，并按拍摄日期排序。所有内容都集中在一个页面上，以便于搜索和浏览。 This would be very difficult or even impossible to do in a template-ing language, but is trivial with a custom site generator. 想要用（现成的）模板语言做到这一点会非常困难甚至不可能，但对于自定义的网站生成器来说，这易如反掌。 **All of this is contained in a [single C file](/mksite.c)**: It has no configuration files, no external assets and no weird domain-specific-language. The code is ~700 lines, including the template HTML. It's something one person can understand and maintain. **所有这些功能都包含在[一个 C 语言文件](/mksite.c)中**：它没有配置文件，没有外部资源，也没有奇怪的领域特定语言（DSL）。代码大约 700 行（包括 HTML 模板）。这是一个人完全能够理解和维护的量。 I highly recommend doing this: 我强烈推荐你也这么做： * There will never be an update that [breaks your site](https://www.ii.com/hugo-update-nope/). Sure, you could stay on an old version, but it's only a matter of time before you find an annoying bug. 永远不会有[搞崩你网站](https://www.ii.com/hugo-update-nope/)的更新。当然，你可以一直用旧版本，但发现烦人的 Bug 只是时间问题。 * You have complete control: Want to write pages in Emacs [Org-mode](https://github.com/adityaathalye/shite)? LaTeX? AsciiDoc? Plain text? No problem. 你拥有完全的控制权：想用 Emacs [Org-mode](https://github.com/adityaathalye/shite) 写页面？还是 LaTeX？AsciiDoc？纯文本？都没问题。 * Do you need something weird and very specific? Just add it. 你需要某种奇怪且非常具体的功能？加上就是了。 It's not hard to write one: It took only a few hours of work to get mine to the point it could replace [Hugo](https://gohugo.io/) with it's 1000+ dependencies... and mine is written in C: Not exactly the friendliest language. 写一个生成器并不难：我只花几个小时就让它达到了可以替代 [Hugo](https://gohugo.io/)（这就省去了 Hugo 那 1000 多个依赖项）的程度……而且我还是用 C 写的：这可不是什么最友好的语言。 # Switching # 迁移 The longest part of the move was converting all my 100+ blog posts into the new format. This could have been automated, but I wanted the chance to freshen up the writing. (... and it still took less time then configuring [Hugo](https://gohugo.io/).) 迁移过程中最耗时的部分是将我那 100 多篇博客文章转换成新格式。这本可以自动化完成，但我想借此机会润色一下文章。（……而且这花的时间依然比配置 [Hugo](https://gohugo.io/) 要少。） I started this blog to get better at writing: All the posts from before 2023 are *bad*. 我写这个博客的初衷是为了提高写作水平：2023 年以前的所有文章都写得*很烂*。 Really, wanting to delete everything out of shame proves it's working. But since this is [a blog](/misc/starting_a_blog/), I don't have to delete the old stuff: I can just fix all the mistakes. 真的，这种因羞愧而想删掉一切的冲动，正好证明了我在进步。但既然这是[一个博客](/misc/starting_a_blog/)，我不必删除旧东西：我只要修正所有的错误就好了。