命名约定 [name-convention]

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

References

Kodama 程序 [app]

仓库链接: github.com/kokic/kodama.

配置文件 [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 用于指定 的页脚部分是否嵌入关联或被关联 的正文. 值只能是 linkembed.
  • inline-css 开启后将内联 main.cssCSS 文件.
  • output 用于指定 build 模式下的网站输出路径.

[serve]

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

Backlinks

编号系统 [name-convention-1]

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

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

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

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

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

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

1

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