cmarker.typ

This package enables you to write CommonMark Markdown, and import it directly into Typst.

#import "@preview/cmarker:0.1.10"

#cmarker.render(read("simple.md"))

# We can write Markdown!

*Using* __lots__ ~of~ `fancy` [features](https://example.org/).

simple.pdf

This document is available in Markdown and rendered PDF formats.

Contents

1. API
2. References, labels, figures and citations
3. Supported Markdown syntax
4. Interleaving Markdown and Typst
5. FAQ
6. Development

API

We offer two functions: 1. render 2. render-with-metadata

render

render(
  markdown,
  smart-punctuation: true,
  math: none,
  task-list-marker: none,
  h1-level: 1,
  set-document-title: true,
  raw-typst: true,
  html: (:),
  label-prefix: "",
  prefix-label-uses: true,
  heading-labels: "github",
  scope: (:),
  show-source: false,
  blockquote: none,
) -> content

The render function renders the given Markdown and returns content.

markdown

The CommonMark Markdown string to be processed. Parsed with the pulldown-cmark Rust library. You can set this to read("somefile.md") to import an external markdown file; see the documentation for the read function. - Accepted values: Strings and raw text code blocks. - Required.

smart-punctuation

Whether to automatically convert ASCII punctuation to Unicode equivalents: - nondirectional quotations (" and ') become directional (“” and ‘’); - three consecutive full stops (...) become ellipses (…); - two and three consecutive hypen-minus signs (-- and ---) become en and em dashes (– and —).

Note that although Typst also offers this functionality, this conversion is done through the Markdown parser rather than Typst. - Accepted values: Booleans. - Default value: true.

math

A callback to be used when equations are encountered in the Markdown, or none if it should be treated as normal text. Because Typst does not support LaTeX equations natively, the user must configure this. - Accepted values: Functions that take a boolean argument named block and a positional string argument (often, the mitex function from the mitex package), or none. - Default value: none.

For example, to render math equation as a Typst math block, one can use:

#import "@preview/mitex:0.2.7": mitex
#cmarker.render(`$\int_1^2 x \mathrm{d} x$`, math: mitex)

task-list-marker

A callback which can be used to render Markdown task lists, or none if task lists are not supported. The callback will be called with true if the checkbox is to be checked (- [x]), and false if it is unchecked (- [ ]).

• Accepted values: Functions from booleans to content, or none.
• Default value: none.

You may want to use cheq to provide the checkboxes:

#import "@preview/cheq:0.3.1"

#cmarker.render(
  ```md
  - [ ] Not checked
  - [x] Checked
  ```,
  task-list-marker: checked => if checked { cheq.checked-sym() } else { cheq.unchecked-sym() },
)

h1-level

The level that top-level headings in Markdown should get in Typst. When set to zero, top-level headings are treated as titles, ## headings become = headings, ### headings become == headings, et cetera; when set to 2, # headings become == headings, ## headings become === headings, et cetera. - Accepted values: Integers in the range [-128, 127]. - Default value: 1.

set-document-title

Whether to emit a #set document(title: […]) line for #title()s.

If you encounter a “document set rules are not allowed inside of containers” error, you should set this to false, and potentially add a #set document(title: […]) line manually.

This has effect when h1-level is zero and you have a top-level (i.e. #) heading.

• Accepted values: Booleans.
• Default value: true.

raw-typst

Whether to allow raw Typst code to be injected into the document via HTML comments. If disabled, the comments will act as regular HTML comments. - Accepted values: Booleans. - Default value: true.

For example, when this is enabled, will result in a circle in the document (but only when rendered through Typst). See also [ and ``](#interleaving-markdown-and-typst), which is the inverse of this.

html

The dictionary of HTML elements that cmarker will support. - Accepted values: Dictionaries whose keys are the tag name (without the surrounding <>) and whose values can be: - ("normal", (attrs, body) => [/* … */]): Defines a normal element, where attrs is a dictionary of strings, body is content, and the function returns content. - ("void", (attrs) => [/* … */]): Defines a void element (e.g. `

,,