开始 [getting-started]

    1. 安装 [install]

      目前, 用户可以根据目标设备的架构直接从 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. 在 1.0 版本释放前, 每次发布都可能包含破坏性变更, 不过我们会努力使迁移成本尽可能的低.

      2. 新建站点 [new-site]

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

        要创建一个新的 kodama 风格站点, 请执行

        kodama new site <PATH>

        用户可以在此目录的 trees/ 文件夹下进行 Markdown 或 Typst 写作.

        首次使用 serve 功能前, 用户应该检查 配置文件 中 [serve] 字典的 command 键, 默认值调用了 miniserve 程序, 因此用户可以选择安装 miniserve 或者将其修改为其他可用的本地服务器. 如安装了 python 的用户可以将其替换为

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

        References

        配置文件 [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 时开启本地服务器的指令.