Link rules [link-rules-en-US]

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 1 and internal links 2 should be absolute paths relative to the current workspace, starting with /.

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.

Backlinks

链接规则 [link-rules]

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

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

嵌入语法 [embed-syntax]

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

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

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

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

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

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

内联语法 [inline-syntax]

内联 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).
  • 各个参数的值之间使用 - 分隔. mathmargin 的位置是固定的, 换言之, 如果这两个参数同时出现, 你只能将 margin 写在 math 之后. margin 由形如 {x}-{y} 的文本构成, xy 是任何有效的 Typst 长度值, 如 0pt-2pt. 当 y 缺失时, y 会采用 x 的值.