节 [section][edit]

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

References

Kodama 程序 [app][edit]

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

受限于 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]

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

嵌入 [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 可以认为就是文档的唯一标识符.

写作 [writing][edit]

在使用 Typst 文档写作时, 请务必导入 _lib/kodama.typ 并 #show: kodama. 这段代码将保证 Typst 文档转换为网页后, 其公式内容能够正确显示. 除此之外, 这段代码也会改善 Tinymist 等本地预览工具的使用体验.

对于 trees 文件夹内的 Typst 文件, 需要遵循以下后缀规范:

如果其属于库文件. 即, 不直接产生具体文档, 请使用 .typ 作为文件后缀, 且放置于以 _ 或 . 作为名称首字符的目录内. ¹

而对于包含内容的 Typst 文档, 请统一使用 .typst 后缀.

¹
因为通常的 .typ 文件将编译为独立 SVG 图像, 此功能用于在 Markdown 文档内以图像形式嵌入 Typst 编译产物.

Backlinks

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

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

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

新建站点 [new-site][edit]

用户在安装后, 可以执行 kodama -V 或 kodama --version 检查是否安装成功.

要创建一个新的 Kodama 站点, 请执行:

kodama new site <PATH>

用户可以在该目录的 trees/ 下进行 Markdown 或 Typst 写作.

首次使用 serve 前, 建议检查配置文件中 [serve] 的 command. 默认命令依赖 miniserve, 你可以安装它, 或改为当前设备可用的本地服务命令. 例如:

command = ["python", "-m", "http.server", "-d", "<output>"]

如果用户需要生成 VSCode 风格的 snippets 文件, 进而借助其节代码补全功能 ¹, 可在 Kodama 站点文件夹内执行

kodama snip --section

除此之外, kodama snip 也可以用于生成 $\KaTeX$ 宏补全文件和 inline-section 可用代码片段.

$ kodama snip --help

Generate VSCode style snippets file

Usage: kodama snip [OPTIONS]

Options:
  -c, --config <CONFIG>  Path to the configuration file (e.g., "Kodama.toml") [default: ./Kodama.toml]
      --katex            Generate `.vscode/katex.code-snippets`
      --section          Generate `.vscode/section.code-snippets`
      --inline-section   Generate `.vscode/inline-section.code-snippets`
  -h, --help             Print help

Snippets 补全功能在非 VSCode 的编辑器上是否可用需要自行探索.