Kodama 教程 [tutorials]

December 31, 2024
kokic
en-US

安装 [install]

December 31, 2024
kokic
en-US

你可以根据目标设备的架构直接从 Github Release 页面下载二进制文件. 在 Termux 等 Android 环境中使用请选择 aarch64-unknown-linux-musl 架构.

确保 Kodama 位于可执行目录.
确保 Kodama 有可执行权限.
如果你乐意, 将 Kodama 添加到环境变量.
Kodama 不内置 Typst, 因此如果你的内容涉及 Typst 文本, 你需要保证环境变量中有可用的 Typst 程序.

当 Github Release 页面缺少适合你设备的文件时, 你可以从源代码开始自己构建, 这也很容易.

编译 [compile]

January 4, 2025
kokic
en-US

指令 kodama compile 或缩写为 kodama c 将根据输入的 Markdown 工作区路径构建出 HTML 文件. 默认位于工作区路径的 publish 文件夹下.
尽管有 --root 参数, 但仍然建议所有用户在 index.md 文件所在的目录下执行 kodama c.

shell [compile-help]

$ kodama c --help
Compile current workspace dir to HTMLs

Usage: kodama.exe compile [OPTIONS]

OOptions:
  -b, --base <BASE>                Base URL or publish URL (e.g. https://www.example.com/) [default: /] 
  -o, --output <OUTPUT>            Path to output dir [default: ./publish]
  -r, --root <ROOT>                Configures the project root (for absolute paths) [default: ./]       
  -d, --disable-pretty-urls        Disable pretty urls (`/page` to `/page.html`)
  -s, --short-slug                 Hide parents part in slug (e.g. `tutorials/install` to `install`)    
  -f, --footer-mode <FOOTER_MODE>  Specify the inline mode for the footer sections [default: link] [possible values: link, embed]
  -h, --help                       Print help

举例来说, 如果最终部署到的 URL 为 https://www.example.com/blog, 这并非该域名的根目录, 为了保证生成链接的正确性, 用户应该指定 --base 这一编译参数, 即

kodama c -b=https://www.example.com/blog

注意. 当然, 如果用户只是在本地使用, 就不必考虑这个问题了.

本地预览 [publish]

December 31, 2024
kokic
en-US

如果你希望在本地查看生成页面 publish/ 的效果, 通常你需要一个本地 http 服务器. 你可以使用任何你熟悉的工具完成这件事. 此处推荐 miniserve, 安装后在 Kodama 项目的根路径执行如下指令即可.

miniserve ./publish --index index.html --pretty-urls

链接规则 [link-rules]

January 15, 2025
kokic
en-US

虽然 Kodama 所处理的 Markdown 文件从语法上说是完全符合 CommonMark 标准的, 但是由于它实现了 CommonMark 之外的许多功能, 为了从语法上区分开来, 用户在使用这些额外的功能时, 请务必遵循下面的规则.

首先需要强调的是, 无论是嵌入文件 ¹ 还是内部链接 ² 的路径, 都应该是以 / 开头的相对于当前工作区的绝对路径.

嵌入语法 [embed-syntax]

January 15, 2025
kokic
en-US

嵌入语法和标准链接语法 [text](url) 的区别在于, 嵌入的 url 带有特殊的后缀, 并且只能是以下几种:

.md#:embed, 嵌入 Markdown.
.typ#:block, 嵌入 Typst 编译后的 SVG, 并居中展示为块级元素.
.typ#:span, 嵌入 Typst 编译后的 SVG, 并展示为行间元素 (不常用).
.typ#:shared, 在当前文件的上下文中导入该 Typst 文件, 此时 text 用于提供被导入的定义范围, 如所有定义 *. 配合内联 Typst 语法使用.

这些特殊后缀采用这种语法的一个原因是, 许多 Markdown 编辑器 ¹ 能够正确识别从而享受文件之间的跳转功能.

大部分时候, 嵌入语法的 text 都是空着的, 不过由于只有 Markdown 的嵌入才会产生子 section, 此时 text 能用于设置 section 默认是否展开以及在目录中的状态. 这些设置由一系列特定字符构成, 它们对应的功能彼此独立, 因此书写的先后顺序可以任意.

+, 表示当前 section 使用计数器.
-, 默认折叠当前 section. 相应的, 如果这个 section 也有一系列子 section, 这些子 section 将不会出现在当前页面的目录里.
., 在当前页面的目录里隐藏这个 section.

如 Visual Studio Code.

很多时候, 对于相当简单的 Typst 文本, 用户会希望有一种方式在展示上对应于 $\KaTeX$ 语境下的行内公式, 这就是内联 Typst.

内联语法 [inline-syntax]

January 15, 2025
kokic
en-US

内联 Typst 也许是 Kodama 真正的优势所在, 因为设计者做了许多努力使其表现的就和 $\KaTeX$ 行内公式一样或者至少非常接近, 从而不会让 Typst 的那部分行内公式在与 $\KaTeX$ 混合编排时显得廉价.

内联 Typst 也采用链接类语法, 但是此时不会有任何文件被链接. url 部分用于指定内联模式和 margin 参数, 绝大部分情况下, 用户都不需要自己手动设置 margin 参数便可以取得较好的呈现效果. 内联模式是一个为了方便 Markdown 编辑器本身的预览功能而设计的参数, 当用户填入 math 时, text 部分的内容就会被自动加上 ${}$ 再交给 Typst 编译. 以下是一些例子:

[$x^2$](inline), x^2 同时是合法的 $\KaTeX$ 公式和 Typst 公式, 此时 Markdown 编辑器本身的预览功能可将它正确呈现为 $x^2$. 虽然这个例子简单到根本没有任何理由使用 Typst.
# 在 Typst 当中是一个高频率使用的字符, 此时如果依然手写 ${}$ 则会导致编辑器内 Markdown 预览的体验不佳, 这就是内联模式参数 math 的意义. 现在你可以将第一个例子写为 [x^2](inline-math).
各个参数的值之间使用 - 分隔. math 和 margin 的位置是固定的, 换言之, 如果这两个参数同时出现, 你只能将 margin 写在 math 之后. margin 由形如 {x}-{y} 的文本构成, x 和 y 是任何有效的 Typst 长度值, 如 0pt-2pt. 当 y 缺失时, y 会采用 x 的值.

被嵌入的文件是独立的 Markdown 或者 Typst, 嵌入这一操作会将被链接文件的内容合并到链接的位置, 对于 Markdown, 它将成为一个子 section.

内部链接用于链接当前 Kodama 项目的其他 Markdown 文件, 与外部链接相比, 内部链接使用一种特殊的样式.

持续集成 [github-workflow]

January 15, 2025
kokic
en-US

一个可供参考的 Github Workflow 配置如下 ¹. 唯一需要注意的是环境变量 $PAGE_URL, 用于指定待部署页面的 URL, 你可以在仓库的 settings/variables/actions 设置它们.

workflow.yml [workflow-yml]

name: Deploy Kodama site to Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["main"]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

# Default to bash
defaults:
  run:
    shell: bash

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Install Kodama & Typst
        run: |
          cargo install --git https://github.com/kokic/kodama.git
          sudo snap install typst
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: recursive
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v5
      - name: Build with Kodama
        run: |
          kodama c -b $PAGE_URL
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./publish

# Deployment job
  deploy:
    environment:
      name: github-pages
      url: $PAGE_URL
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

由 Hong Jiarong 提供.

Backlinks

Kodama Tutorials [index-en-US]

December 31, 2024
kokic
zh-CN

Installation [install-en-US]

December 31, 2024
kokic
zh-CN

You can directly download the binary file from the Github Release page based on the architecture of your target device. For use in Android environments like Termux, choose the aarch64-unknown-linux-musl architecture.

Ensure that Kodama is located in an executable directory.
Make sure Kodama has executable permissions.
If you wish, add Kodama to your environment variables.
Kodama does not come with Typst built-in, so if your content involves Typst text, you need to ensure that a Typst program is available in your environment variables.

When the Github Release page does not have a file suitable for your device, you can start by building from source code yourself, which is also quite easy.

Compilation [compile-en-US]

January 4, 2025
kokic
zh-CN

The command kodama compile or its abbreviation kodama c will build HTML files based on the input Markdown workspace path. By default, these files are placed in the publish folder within the workspace path. Even with the --root parameter, it is still recommended for all users to execute kodama c in the directory where the index.md file is located.

shell [compile-help]

$ kodama c --help
Compile current workspace dir to HTMLs

Usage: kodama.exe compile [OPTIONS]

OOptions:
  -b, --base <BASE>                Base URL or publish URL (e.g. https://www.example.com/) [default: /] 
  -o, --output <OUTPUT>            Path to output dir [default: ./publish]
  -r, --root <ROOT>                Configures the project root (for absolute paths) [default: ./]       
  -d, --disable-pretty-urls        Disable pretty urls (`/page` to `/page.html`)
  -s, --short-slug                 Hide parents part in slug (e.g. `tutorials/install` to `install`)    
  -f, --footer-mode <FOOTER_MODE>  Specify the inline mode for the footer sections [default: link] [possible values: link, embed]
  -h, --help                       Print help

For example, if the final deployment URL is https://www.example.com/blog, which is not the root directory of the domain, to ensure the correctness of the generated links, the user should specify the --base compilation parameter, like so:

kodama c -b=https://www.example.com/blog

Note that this is only necessary if you are deploying to a specific subdirectory. If you are using it locally, you don’t need to consider this issue.

Preview [publish-en-US]

December 31, 2024
kokic
zh-CN

If you want to view the generated pages in the publish/ directory locally, you typically need a local HTTP server. You can use any tool you are familiar with to accomplish this. Here, miniserve is recommended. After installing it, you can run the following command in the root path of your Kodama project to serve the pages locally.

miniserve ./publish --index index.html --pretty-urls

Link rules [link-rules-en-US]

January 15, 2025
kokic
zh-CN

Although the Markdown files processed by Kodama are syntactically compliant with the CommonMark standard, it implements many features beyond CommonMark. To distinguish these additional features syntactically, users must follow the rules below when using these extra functionalities.

First and foremost, it is important to emphasize that paths for both embedded files ¹ and internal links ² should be absolute paths relative to the current workspace, starting with /.

Embed Syntax [embed-syntax-en-US]

January 15, 2025
kokic
zh-CN

The difference between the embed syntax and the standard link syntax [text](url) is that the url in the embed has a special suffix, and it can only be one of the following:

.md#:embed, to embed Markdown.
.typ#:block, to embed the compiled SVG from Typst and display it as a block-level element centered.
.typ#:span, to embed the compiled SVG from Typst and display it as an inline element (less commonly used).
.typ#:shared, to import the Typst file within the context of the current file, where text is used to provide the scope of the imported definitions, such as all definitions with *. This is used in conjunction with inline Typst syntax.

The reason for using these special suffixes in this syntax is that many Markdown editors ¹ can recognize them correctly, allowing for navigation between files.

Most of the time, the text in the embed syntax is left empty. However, since only Markdown embeds create child sections, the text can be used to set whether the section is expanded by default and its state in the table of contents. These settings are made up of a series of specific characters, and their functions are independent of each other, so the order in which they are written can be arbitrary.

+, indicates that the current section uses a counter.
-, collapses the current section by default. Consequently, if this section also has a series of child sections, these child sections will not appear in the table of contents on the current page.
., hides this section in the table of contents on the current page.

Such as Visual Studio Code.

Often, for quite simple Typst text, users will want a way to display it inline, corresponding to the inline math context in $\KaTeX$. This is where inline Typst comes in.

Inline Syntax [inline-syntax-en-US]

January 15, 2025
kokic
zh-CN

Inline Typst might be the true strength of Kodama, as the designers have made great efforts to make it behave just like or at least very close to $\KaTeX$ inline formulas, so that the inline formulas written in Typst do not appear inferior when mixed with $\KaTeX$.

Inline Typst also uses link-like syntax, but in this case, no file is actually linked. The url part is used to specify the inline mode and the margin parameter. In most cases, users do not need to manually set the margin parameter to achieve a good presentation. The inline mode is a parameter designed for the convenience of the Markdown editor’s own preview feature. When the user enters math, the content of the text part is automatically enclosed with ${}$ before being compiled by Typst. Here are some examples:

[$x^2$](inline), x^2 is a valid formula for both $\KaTeX$ and Typst. In this case, the Markdown editor’s own preview feature can correctly display it as $x^2$. However, this example is so simple that there is no real reason to use Typst.
# is a frequently used character in Typst. If you still write ${}$ manually, it would lead to a poor preview experience in the editor. This is where the inline mode parameter math comes into play. Now you can write the first example as [x^2](inline-math).
Values of parameters are separated by -. The positions of math and margin are fixed, which means that if both parameters are present, you can only write margin after math. The margin is composed of text in the form of {x}-{y}, where x and y are any valid Typst length values, such as 0pt-2pt. When y is missing, y will adopt the value of x.

The embedded file can be either a standalone Markdown or Typst file. The embedding operation will merge the content of the linked file into the position of the link. For Markdown, it will become a child section.

Internal links are used to link to other Markdown files within the same Kodama project. Compared to external links, internal links use a special style.

Github CI [github-workflow-en-US]

January 15, 2025
kokic
zh-CN

A reference GitHub Workflow configuration can be found here ¹. The only thing to note is the environment variable $PAGE_URL, which is used to specify the URL of the page to be deployed. You can set these in the settings/variables/actions section of your repository.

workflow.yml [workflow-yml]

name: Deploy Kodama site to Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["main"]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

# Default to bash
defaults:
  run:
    shell: bash

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Install Kodama & Typst
        run: |
          cargo install --git https://github.com/kokic/kodama.git
          sudo snap install typst
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: recursive
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v5
      - name: Build with Kodama
        run: |
          kodama c -b $PAGE_URL
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./publish

# Deployment job
  deploy:
    environment:
      name: github-pages
      url: $PAGE_URL
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Provided by Hong Jiarong.