Kodama 程序 [app][edit]

Kodama 是一款用于构建双链风格笔记的命令行程序. 是笔者为自己打造的博客工具、笔记软件、维基系统. Kodama 程序所生成网站的默认风格受到软件 Forester 的深刻影响.

受限于 Markdown 本身表达能力的缺陷, Kodama 无法像 Forester 那样完全控制文档数据的处理模式. 在其他方面提供了更多便捷的特性, 包括但不限于:

1. 色彩特性 [feature-color][edit]

内置一套精心设计的暗主题, 明暗主题切换默认遵循浏览器主题偏好.
可以安装其他色彩风格的主题, 主题文件仓库位于 Github - themes.
使用 Typst 所生成的公式或图像中的文本或线条颜色, 会自动的跟随颜色主题方案而变化, 无论在何种主题之下都有正确清晰的显示效果.
用户可以同时为网站部署多种主题, 并灵活地在他们之间切换. 即使页面刷新或者浏览器关闭, 之前所选的主题方案也不会受到影响.

2. 零成本使用 Typst 写作 [feature-typst][edit]

用户可以自由的组合 Markdown 和 Typst 所构建出的节. 例如, 本节就来自 Typst 文档. 而节 Kodama 则完全是 Markdown 文档.
针对 Typst 公式渲染的布局优化. 能自动正确对齐与文本不等高的内联公式.
- 权级的模形式具有对称性 , 其中 , 并且要求在的所有尖点处全纯.
- 射影平面
Tinymist 等工具的完全可用性. 即使目标为 HTML 文件, 原始 Typst 文档也能正常使用 Tinymist 的预览功能.

本节源文件可于 Github - feature-typst.typst 处查看.

3. 多语言文本优化 [feature-text][edit]

印欧语系开发者因文化差异, 其设计的工具如 Forester 往往未能考虑汉藏语系用户的需要和使用习惯. 例如块级引用内的汉字默认被显示为斜体, 但汉字本身并不存在 “斜体” 这一概念, 合适的对应物为楷体. 举例如下.

All of the answers you seek lie hidden in the sun 答えの潜む琥珀の太阳 If I hadn’t met you, 出会わなければ my life would’ve been in the darkness forever 不死なる瞬き持つ魂伤つかないで In my wings are the powers of immortality 仆の羽根 But by meeting you my whole life has changed この持ち知るため生まれてきた You give light to me hope to me strength into my life

Rise 空には太陽が Force あなたには強さが似合う Days 涙は夢をみて Stage 未来を描いては掴む世界中風さえ在るのならどこまでもぼくらは飛ベると誓い合う絆が見えたダイアモンドから夢を放つペルセウスまだ見ぬチカラをその瞳めに秘めて光の翼が虹をかけてゆく Field of dreams 輝くあなたを信じてる

这个礼拜我们聚集了全国数学精英做 2025 annual math review. 讲他们的重要工作。我本人会參加每一埸演讲。但是我很失望：求真書院的学生參加的学生很少，都躲在甚么地方了？做世界一流的研究，就如攀登高峰，需要長期準備工作，準備好工具。当年衛青霍去病出塞征伐匈奴，入千里無人之地，义無反顧，弱则死于绝域，霍去病年不过二十，八百骑直走匈奴王庭，第一次成功的擊败匈奴，抵定河西走廊，立中国千載之功！何其壮哉！今我求真子弟，不思科研之極至，立不朽之功。躲在家中玩耍游戏，置一流学問於不顾！本人六十年来，日出而作，每天工作至少八个小时，猶恐不及，未達天人之交，有负家国之望！竊为诸君今日所志所为，羞之羞之！

References

Kodama 程序 [app][edit]

受限于 Markdown 本身表达能力的缺陷, Kodama 无法像 Forester 那样完全控制文档数据的处理模式. 在其他方面提供了更多便捷的特性, 包括但不限于:

色彩特性 [feature-color][edit]

内置一套精心设计的暗主题, 明暗主题切换默认遵循浏览器主题偏好.
可以安装其他色彩风格的主题, 主题文件仓库位于 Github - themes.
使用 Typst 所生成的公式或图像中的文本或线条颜色, 会自动的跟随颜色主题方案而变化, 无论在何种主题之下都有正确清晰的显示效果.
用户可以同时为网站部署多种主题, 并灵活地在他们之间切换. 即使页面刷新或者浏览器关闭, 之前所选的主题方案也不会受到影响.

零成本使用 Typst 写作 [feature-typst][edit]

用户可以自由的组合 Markdown 和 Typst 所构建出的节. 例如, 本节就来自 Typst 文档. 而节 Kodama 则完全是 Markdown 文档.
针对 Typst 公式渲染的布局优化. 能自动正确对齐与文本不等高的内联公式.
- 权级的模形式具有对称性 , 其中 , 并且要求在的所有尖点处全纯.
- 射影平面
Tinymist 等工具的完全可用性. 即使目标为 HTML 文件, 原始 Typst 文档也能正常使用 Tinymist 的预览功能.

本节源文件可于 Github - feature-typst.typst 处查看.

多语言文本优化 [feature-text][edit]

All of the answers you seek lie hidden in the sun 答えの潜む琥珀の太阳 If I hadn’t met you, 出会わなければ my life would’ve been in the darkness forever 不死なる瞬き持つ魂伤つかないで In my wings are the powers of immortality 仆の羽根 But by meeting you my whole life has changed この持ち知るため生まれてきた You give light to me hope to me strength into my life

Rise 空には太陽が Force あなたには強さが似合う Days 涙は夢をみて Stage 未来を描いては掴む世界中風さえ在るのならどこまでもぼくらは飛ベると誓い合う絆が見えたダイアモンドから夢を放つペルセウスまだ見ぬチカラをその瞳めに秘めて光の翼が虹をかけてゆく Field of dreams 輝くあなたを信じてる

这个礼拜我们聚集了全国数学精英做 2025 annual math review. 讲他们的重要工作。我本人会參加每一埸演讲。但是我很失望：求真書院的学生參加的学生很少，都躲在甚么地方了？做世界一流的研究，就如攀登高峰，需要長期準備工作，準備好工具。当年衛青霍去病出塞征伐匈奴，入千里無人之地，义無反顧，弱则死于绝域，霍去病年不过二十，八百骑直走匈奴王庭，第一次成功的擊败匈奴，抵定河西走廊，立中国千載之功！何其壮哉！今我求真子弟，不思科研之極至，立不朽之功。躲在家中玩耍游戏，置一流学問於不顾！本人六十年来，日出而作，每天工作至少八个小时，猶恐不及，未達天人之交，有负家国之望！竊为诸君今日所志所为，羞之羞之！

节 [section][edit]

节是 Kodama 写作中的基本概念. 每个节都将被处理为一个 HTML 文件. 节可以来自 Markdown 文档或 Typst 文档. 节之间的链接和组合构成了 Kodama 写作的基本模式.

Backlinks

零成本使用 Typst 写作 [feature-typst][edit]

用户可以自由的组合 Markdown 和 Typst 所构建出的节. 例如, 本节就来自 Typst 文档. 而节 Kodama 则完全是 Markdown 文档.
针对 Typst 公式渲染的布局优化. 能自动正确对齐与文本不等高的内联公式.
- 权级的模形式具有对称性 , 其中 , 并且要求在的所有尖点处全纯.
- 射影平面
Tinymist 等工具的完全可用性. 即使目标为 HTML 文件, 原始 Typst 文档也能正常使用 Tinymist 的预览功能.

本节源文件可于 Github - feature-typst.typst 处查看.

嵌入 [link-embed][edit]

嵌入是一种特殊的 Markdown 链接动作, 用于把目标文档展开到当前位置. 语法是在普通链接的 URL 后追加 #:embed, 例如 [+](./doc.md#:embed). Kodama 程序会在编译阶段解析目标文档并内联其内容.

相较于站内引用, 嵌入直接渲染目标文档的内容块.
嵌入时可以覆盖显示标题. 如 [+ 自定义标题](./doc.md#:embed) 会使用 自定义标题 作为嵌入块标题, 生成的目录也遵循此处设置.
嵌入选项由链接文本开头的 +, -, . 控制, 可组合使用:
- +: 开启编号.
- -: 折叠嵌入块.
- .: 不出现在目录中.
默认无编号、不折叠、出现在目录.

使用 Markdown 或 Typst 作为源文档时, 以下路径形式都可用于触发嵌入:

/trees/path/to/doc.md#:embed
/trees/path/to/doc.typst#:embed
./relative/path/doc.md#:embed
./relative/path/doc.typst#:embed
../parent/path/doc.md#:embed
../parent/path/doc.typst#:embed

与站内引用一样, 推荐在路径中保留 .md 或 .typst 扩展名, 这样通常更利于 VSCode 的跳转与补全体验.

站内引用 [link-local][edit]

站内引用或称内部链接, 是一种特殊的 Markdown 链接, 也是构造双链文档的基本手段. Kodama 程序会在编译阶段解析站内引用所指向文档的标题和 slug ¹ 信息.

当站内引用的文字部分为空时, 即 [](./doc.md) 这种情况, Kodama 程序会使用所指向文档的标题作为此链接的文字部分.
当站内引用的文字部分不为空时, 链接的显示文本即为此文字部分. 而所指向文档的标题会作为链接元素的 title 属性, 在指针悬停时可见.
- 当所指向文档的标题包含特殊内容 (如 KaTeX 代码) 时, 这些特殊内容往往不适合在悬停处展示. 此时所指向文档设置的 page-title 会作为实际的悬停展示标题.
考虑一个文档 $A$, 此文档包含一个站内引用指向文档 $B$, 记为 $A \to B$. 对于通常的网页来说, 查看文档 $A$ 时访问文档 $B$ 是轻而易举的; 但查看文档 $B$ 时就难以知道文档 $A$ 的存在. 为此 Kodama 程序会为每个文档页面都生成反向链接并放置于页面底部, 这就提供了路径 $B \to A$.
当文档 $A$ 内包含大量站内引用指向文档 $B_1, B_2, B_3, \cdots$ 时, 将这些链接信息从文档中的不同位置整理到一个集中区域, 是完全有必要的. 为此, 用户可以在所需文档的元数据部分添加 asref: true, 这将使得此文档被认为是一条参考, 并收集在页面底部的 References 位置.
- 如果文档的元数据 taxon 内容以 reference 或者 参考 开头, 则此文档也会被认为是一条参考.
- 用户也可以直接在配置文件的 [build] 处将 asref = false 改为 asref = true. 这将使得所有的文档都被认为是参考.

使用 Markdown 作为文档格式写作时, 以下链接会被识别为站内引用:

/trees/path/to/doc.md
/trees/path/to/doc.typst
./relative/path/doc.md
./relative/path/doc.typst
../parent/path/doc.md
../parent/path/doc.typst

诸如此类的链接可以最大程度地配合 VSCode 编辑器的跳转功能, 以便获得最佳的编辑体验. 路径 /path/to/doc.md 目前虽然也是合法的, 但编辑器往往无法确定目标文件位置, 我们不建议使用.

简单的说, slug 可以认为就是文档的唯一标识符.

节 [section][edit]

代码高亮 [highlight][edit]

Kodama 程序本身并未提供代码高亮支持, 但用户想要为其配置一些主流的高亮工具也不是一件难事. 我们以 highlight.js 为例. 在工作区根目录新建 import-style.html, 内容如下:

Highlight.js [highlight.js][edit]

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/obsidian.min.css">
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/languages/xml.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/languages/shell.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/languages/rust.min.js"></script>

<script>
  hljs.configure({ cssSelector: 'pre code[class^="language-"]' });
  hljs.highlightAll();
</script>

<style>
  pre {
    background-color: transparent;
  }

  .hljs {
    background-color: var(--background-color-code);
  }

  .hljs,
  .hljs-subst.hljs-class .hljs-title,
  .hljs-code,
  .hljs-section,
  .hljs-title.class_ {
    color: var(--text-color);
  }
</style>

我们还额外设置了一些样式, 用于调整浏览器明暗主题下的代码高亮行为.

命名约定 [naming][edit]

从软件的角度讲, 我们不应该要求用户以何种方式给他们的文件起名, 但确定一种灵活且规律的命名方式确实能帮助我们在给文件命名时省去不少时间.

编号系统 [NCNS][edit]

这套方法使用固定长度的字符作为文件名, 每个字符取自 0-9 和 A-Z. 换言之, 如果长度为 $4$ ¹, 那么你可以从 0000 一直使用到 ZZZZ, 总共 $36^4 = 1679616$ 也就是大约 168 万种可能.

在 --edit 功能的帮助下, 使用完全不涉及内容信息的编号作为文件名的命名方式在使用体验上已经得到了很大的改善. 它的优势也比较明显:

你可以在 $\mathcal{O}(1)$ 时间甚至 1ms 内决定一个新文件应该叫什么.
内容无关. 有时候这是一件好事, 举例来说, 当你对文件 7A96 的内容做出任何更改时, 都无需修改文件名以及引用了 7A96 的文件.

我们也能据此写出这种方式的缺点:

非语义的命名. 除了某种可能存在的字典序外, 我们无法从文件名获得更多信息, 为了快速从浏览中的页面定位到文件, 我们还需要像是 --edit 这种依赖编辑器程序的功能.

在个人计算机流行前的那些岁月里, Niklas Luhmann 使用了一种基于编号系统的权衡方案, 他为这些编号赋予了特定含义, 例如第一个字符总是表示主题的编号, 而第二个字符代表对主题的补充. 例如, 1A 和 1B 在 1 这个分类下是相关的, 但在 A 的层面, 它们又无关.

如果你在别处也看到了这种风格, 不必认为是巧合. 它们极有可能都无意识地来自四字神名. 遵循这种方式, 写作者总有一天会写出以 YHWH 作为名字的条目.

语义风格 [NCSM][edit]

即, 名字是对内容的概述. 因此一旦你确定了文章的标题, 那也就同时确定了这种风格下的文件名.

如果你是一个从其他 SSG 工具迁移而来的用户, 你博客文章的文件名大概率就是这种方式. 只要你不是有特别严重的强迫症, 用这种方式命名文件并不会占用太多时间.

也不必刻意要求文件名能精确描述文件内容, 结合编号系统一起使用会使名字的灵活性更高.