链接规则 [link-rules]

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

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

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

Backlinks

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 /.

Embed Syntax [embed-syntax-en-US]

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 1 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.

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]

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.