使用 Pandoc 生成静态博客

项目背景

受一个博客的启发，我对 Pandoc 产生了兴趣。这里记录下我昨天和今天的学习收获。

md 转 html

pandoc --toc -V toc-title:"Table of Contents" --section-divs  -c main.css -A src/sources/footer.html -f markdown+east_asian_line_breaks "src/blog/2023/pandoc-blog.md" -s -o "dist/pandoc-blog.html"

上面这条命令就是用来生成本篇 html 的，每部分的作用如下：

--toc: 生成 Table of Contents
-V toc-title:"Table of Contents": 给 Table of Contents 指定标题
--section-divs: 内容块使用 section 标签
-c main.css: 加载外部 css
-A src/sources/footer.html: 添加通用的页脚 html 块
-f markdown+east_asian_line_breaks "src/blog/2023/pandoc-blog.md": 指定输入格式和文件路径，使用东亚文字扩展（忽略单行换行符后面的空格）
-s: 输出完整的 html 页面，而不仅是代码块
-o "dist/pandoc-blog.html": 输出到文件中，如果文件路径中有-等特殊字符，需要加引号处理

CSS 样式

main.css 用 Tailwind CSS 生成，对页面样式做了一些简单的重写。目前仅覆盖标题、目录、代码高亮等，随着内容元素的增加，比如图片、引用、表格等，再追加相应的样式。

目前这个样式表还比较简陋，作为一个设计苦手，暂时也只能做到这样了，等找到一个好的参考页面，再来优化，目前来说，我个人还算满意。

@tailwind base;
@tailwind components;
@tailwind utilities;

@layer base {
  body {
    @apply mx-auto my-6 max-w-4xl space-y-10 px-4 text-justify font-mono text-lg md:my-8 md:px-6 lg:my-10 lg:px-8;
  }
  h1 {
    @apply my-4 text-3xl font-semibold;
  }
  h2 {
    @apply my-3 text-2xl font-semibold;
  }
  p {
    @apply mb-4;
  }
  a {
    @apply text-blue-700 hover:underline;
  }
  ul {
    @apply list-inside list-disc space-y-1;
  }
  ol {
    @apply list-inside list-decimal;
  }
  #title-block-header {
    @apply text-center;
  }
  .author {
    @apply mb-0 hidden text-sm text-gray-600;
  }
  .date {
    @apply mb-0 inline-flex text-sm text-gray-600;
  }
  #TOC {
    @apply rounded-md border bg-gray-50 p-4;
  }
  #TOC h2 {
    @apply mb-2 mt-0 text-xl font-semibold;
  }
  pre {
    @apply rounded-md border bg-gray-50 p-2 text-sm;
  }
  footer {
    @apply flex w-full justify-evenly border-t pt-4;
  }
  footer a {
    @apply text-sm text-gray-600;
  }
}

自动生成和更新

作为一个静态博客来使用，每一篇文章都手敲命令是不可接受的，并且首页等包含文章列表的页面，也需要有新文章后，能够自动更新。

这里需要一个脚本，需要实现以下功能，目前还没想好，要用什么工具实现这个任务，等完成后再来更新。

自动检测新增加的 md 文件，转换为 html。
自动更新 index 等列表页，按发布时间倒序重新生成 html。

总结

总体上，我觉得使用 Pandoc 来生成静态博客，是一种非常轻量级的体验。学习成本很低，编好脚本以后，也基本上不需要维护，只需要专注于写 md 文档，并推送到托管平台就行了。

我之前用 Next.js 创建过一个博客，后来就疏于更新了，因为每次打开都给我有压力。而我另外一份技术周刊，就是一个纯粹的 md 文档项目，已经连续更新 35 周了，因为每周我只需要花 1 个小时，整理资料写入 md 文档，再提交 github 就行了。越简单的系统，维护的心智成本越低，生命力就越长久。从这个意义上来说，使用 Pandoc 来做静态博客，是很好的一个选择。