参考 [references]

Backlinks

文档索引 [index]

文档分三类, 为参考、教程与示例. 各自用途依次说明如下:

参考 — 强调从程序实现和行为角度解释概念, 常穿插引用源文件.
教程 — 独立且完整的文章合集. 旨在教学, 不宜出现过多技术性内容.
示例 — 纯粹的例子, 以具体说明参考与教程中的操作流程.

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 用于指定节的页脚部分是否嵌入关联或被关联节的正文. 值只能是 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>,
}