开始 [getting-started][edit]

    1. 安装 [install][edit]

      目前, 用户可以根据目标设备的架构直接从 GitHub Release 页面下载二进制文件. 当 GitHub Release 页面缺少适合你设备的文件时, 你可以从 源代码 开始自己构建, 如

      cargo install --git https://github.com/kokic/kodama.git

      如果希望在 Termux 等 Android 环境中使用, 请下载 aarch64-unknown-linux-musl, 或 克隆 源代码 至本地后在其目录下执行

      cargo build --release --target=aarch64-unknown-linux-musl

      我们建议用户使用最新版本, 即便该版本被标记为 pre-release. 由于并非所有 GitHub Release 都能第一时间发现潜在的问题, 如果用户愿意安装 Rust 工具链, 则自行构建是最推荐的安装方式. 在 1.0 版本发布前, 每次发布都可能包含破坏性变更, 不过我们会努力使迁移成本尽可能降低.

      2. 新建站点 [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 文件, 进而借助其 节 代码补全功能 1, 可在 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
        1

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

        3. 命名约定 [naming][edit]

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

          编号系统 [NCNS][edit]

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

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

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

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

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

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

            1

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

            语义风格 [NCSM][edit]

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

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

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