Kodama 程序 [app]

参考

Backlinks

配置文件 [config]

参考

配置文件 Kodama.toml 目前可通过 kodama new c 单独创建, 或者在新建 Kodama 站点时自动生成. 配置文件通常包含以下内容:

[kodama]
trees = "trees" 
assets = "assets"
base-url = "/"

[build]
typst-root = "./"
short-slug = false
pretty-urls = false
footer-mode = "link"
inline-css = false
output = "./publish"

[serve]
edit = "vscode://file/"
output = "./.cache/publish"
command = ["miniserve", "<output>", "--index", "index.html", "--pretty-urls", "--port", "8082"]

`[kodama]`

trees 用于指定文档目录, 即 index.md 等文件所在的文件夹.
assets 用于指定资源目录, 如图片、字体等文件. assets 会在每次构建时自动同步到 publish/<assets>.
base-url 用于指定部署到的域名根路径.

`[build]`

typst-root 用于指定 Typst 构建时的根路径, 见 project root.
short-slug 开启后网页中每个节的 slug 只展示最后一部分.
pretty-urls 开启后网页中每个内部链接将去除 .html 后缀.
footer-mode 用于指定节的页脚部分是否嵌入关联或被关联节的正文. 值只能是 link 或 embed.
inline-css 开启后将内联 main.css 等 CSS 文件.
output 用于指定 build 模式下的网站输出路径.

`[serve]`

edit 用于指定 serve 模式下用于跳转到编辑器的 url 前缀.
output 用于指定 serve 模式下的网站输出路径.
command 用于指定 serve 时开启本地服务器的指令.

链接 [link]

参考

Kodama 程序中的链接语法与 Markdown 链接语法一致, 但前者会依据链接前缀区分一个链接是外部或者内部的, 因为内部链接在 Kodama 程序当中确实是一种特殊的存在, 它自动地将链接到的节和被链接的节关联起来. 除非特别强调, 否则我们所说的链接都是指内部链接.

这种关联指的是, 如果节 $A$ 链接了节 $B$, 那么我们不止可以从 $A$ 所在的页面跳转到 $B$, 也应当有一种方式可以让我们从 $B$ 回到 $A$, 这个流程在如今通常被称为双向连接. 对于使用 Kodama 程序的用户来说, 这种双向连接应当是自动生成.

节 [section]

参考

节是 Kodama 写作中的基本概念. 每个节都将被处理为一个 HTML 文件. 其定义如下

pub struct Section {
    pub metadata: EntryMetaData,
    pub children: SectionContents,
    pub option: SectionOption,
    pub references: HashSet<Slug>,
}

代码高亮 [highlight]

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

import-style.html [highlight.js]

<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/rust.min.js"></script>

<script>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>

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

命名约定 [name-convention]

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

编号系统 [name-convention-1]

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

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

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

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

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

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

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

语义风格 [name-convention-2]

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

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

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