教程 [tutorials]

开始 [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>"]

代码高亮 [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>

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