pdf

Markdown/HTML/Typst to PDF

Overview

Convert Markdown, HTML, or Typst files into PDF documents. Everything is generated locally, with no network required.

Three modes are supported:--mode auto(default, regular document),--mode arithmetic(mental arithmetic practice sheet),--mode pinyin(look at pinyin and write characters). The latter two modes use plain text input and are typeset directly by the CLI.

cyeam pdf README.md                      # 从 Markdown 文件生成 PDF（base64 JSON）
cyeam pdf README.md -o out.pdf           # 从 Markdown 文件生成并保存 PDF
cyeam pdf layout.typ -o out.pdf          # 从 Typst 文件生成并保存 PDF（需要本机 typst）
cat index.html | cyeam pdf               # 从 stdin 读 HTML，输出 base64 JSON
cat README.md | cyeam pdf -o out.pdf     # 从 stdin 读 Markdown 并保存 PDF

Input method selection (important)

cyeam pdf Multiple input methods are supported. Choose the most reliable method according to the current execution environment; do not guess the command format.

Layout format selection (important)

• By default, prefer generating Markdown: suitable for regular documents, explanations, lists, code blocks, and other linear content.
• When the user explicitly requests compactness, space saving, filling the page, multi-column display, free layout, or a better-looking layout, do not generate only ordinary single-column Markdown content.
• Lightweight multiple columns can still use Markdown, but you must use the columns extension syntax supported by cyeam pdf .
• When a freer layout is needed (multiple columns, grids, explicit column breaks, page-level layout), prefer generating a Typst file (.typ), then execute cyeam pdf <file.typ> -o <file.pdf>。
• Do not use HTML/CSS to implement compact or multi-column layout; the current HTML input is only suitable for simple structure conversion, and CSS is not executed as a PDF layout engine.

Markdown multi-column extension

Suitable for scenarios where you still want to keep the Markdown writing experience but need to make short content more compact. Syntax:

::: columns 3
::: column
第一列内容
:::

::: column
第二列内容
:::

::: column
第三列内容
:::
:::

Rules:

• columns The number after it indicates the suggested number of columns, but the actual number of columns is based on the number of column blocks.
• Inside each column , ordinary Markdown is still written.
• Use it only when the user requests layout goals such as compactness, space saving, multiple columns, or filling the page; do not overuse it for ordinary documents.

Typst free layout

Suitable when the user requests free layout, explicit multiple columns, grid, card-style layout, or higher page utilization. Example:

#set page(paper: "a4", margin: 18mm)
#set text(size: 11pt)

#columns(3, gutter: 12pt)[
  第一列内容

  #colbreak()

  第二列内容

  #colbreak()

  第三列内容
]

The Typst file must be saved as .typ and then executed:

cyeam pdf /tmp/layout.typ -o /tmp/layout.pdf --pretty

If typstis not installed on this machine, the command will report an error. In that case, switch to the Markdown columns extension, or prompt the user to install Typst.

Mental arithmetic practice format

The CLI natively supports --mode arithmetic, with no need for Typst. The input is UTF-8 plain text, with one problem per non-empty line (numbering is allowed), and empty lines are ignored; do not mix in Markdown headings, metadata, tables, or answers. The CLI only typesets; it does not automatically generate problems, number them, or add answers.

cyeam pdf questions.txt --mode arithmetic -o practice.pdf
cyeam pdf questions.txt --mode arithmetic --layout grade4 --title "四年级口算" -o practice.pdf
cyeam pdf questions.txt --mode arithmetic --layout vertical -o practice.pdf

--layout Optional standard(default),grade4、large-number、negative、quantity、vertical, corresponding to the table below;--title defaults to "Baby Mental Arithmetic". These two parameters are only used for arithmetic mode. By default, --mode auto retains Markdown/HTML/Typst automatic detection; arithmetic mode takes precedence over the extension, always parses line by line as problems, and supports file or stdin input as well as the original base64 JSON output.

Use when the user requests "mental arithmetic PDF", "mental arithmetic practice sheet", or "typeset in the Baby Mental Arithmetic format". Refer to cyeam_web/controllers/baobao_controller.go in ArithmeticExec(), and take the PDF backend layout as authoritative; do not use the front-end HTML printing logic hard-coded to 100 problems.

• Use A4 portrait (210 × 297 mm), black and white, borderless problem grid; the problem area starts 10 mm from the left, with a total width of 190 mm, starting 32 mm from the top of the page. The header divider line is at 30 mm, spanning 5–205 mm.
• The default header title is “宝宝口算”, 20 pt bold; fourth grade uses the specific problem type title, 13 pt bold. The reference position of the title's top-left is x=10 mm, y=7 mm. In the regular website version, place four short reminders to the right of the title: “检查题目、检查十位、检查个位、检查答案” (8–10 pt); the fourth grade version does not include this set of reminders. CLI native mode uses a regular-weight title, without check reminders, QR code, or name/date fields; use custom Typst when these decorations need to be fully reproduced.
• When reproducing the website version, place a 20 × 20 mm QR code in the upper right corner at x=170 mm, y=7 mm, pointing to https://www.cyeam.com/tool/arithmetic. Custom practice sheets may omit the QR code; metadata such as the title, name, and date from the arithmetic skill should be retained, and the starting position of the problems and the number of rows per page adjusted accordingly to avoid overlap.

Problem type	Rows × columns per page	Capacity per page	Row height	Column width	Problem font size
Regular horizontal mental arithmetic	20 × 5	100 problems	12 mm	38 mm	11.5 pt
General fourth grade problem types	25 × 4	100 problems	10 mm	47.5 mm	9 pt
Fourth grade large numbers g4-large-number, negative numbers g4-negative	25 × 3	75 problems	10 mm	190/3 mm	10 pt
Fourth grade quantitative relationships g4-quantity	25 × 2	50 problems	10 mm	95 mm	10 pt
Non-fourth-grade vertical format (website problem type identifiers end with -2 )	5 × 5	25 problems	48 mm	38 mm	11.5 pt

• Fill the grid in left-to-right, top-to-bottom order. Horizontal problems are left-aligned and vertically centered; vertical-format problems place the problem statement at the top of the cell, with work space preserved below. For the font, refer to Heiti; in practice, use a font that is available and covers Chinese characters and operators.
• For regular fourth grade fill-in-the-blank, leave （　　）, and for quantitative relationships leave a wider （　　　　）; retain units and the complete problem statement. When a long problem does not fit, prioritize increasing the row height or reducing the number of columns, and recalculate the capacity per page; do not truncate the problem statement.
• The problem counts in the table are the per-page capacities of the reference layouts. When the user specifies a problem count or has already provided problems, paginate according to the actual count, leaving the last page blank, and do not add problems arbitrarily just to fill the page. Only when the user requests full pages and does not specify a problem count, generate problems according to the corresponding capacity; the website generator may also return fewer problems than the capacity due to problem bank or deduplication limits.
• Problem content and answers are separate, and by default no answers are attached; when answers are needed, start a separate answer page. When generating problems, follow the grade, problem type, and quantity constraints of the arithmetic skill; this format only specifies PDF layout and does not expand the range of supported problem types.
• By default, use CLI mental arithmetic mode directly, paginate according to the corresponding capacity, and do not add problems to the last page. Long problems wrap automatically within the cell; when they exceed the row height, an error is reported and the problem number is indicated; in that case, shorten the problem statement or choose a wider layout. Vertical format mode places the horizontal problem statement at the top, leaves calculation space below, and does not automatically generate vertical calculations. Use Typst when additional metadata, custom row heights, or vertical calculations are needed; the millimeter dimensions in this section override the 18 mm page margins of the general example above.

Look-at-pinyin-and-write-characters format

When the user requests “看拼音写字 PDF” or “拼音米字格练习纸”, use --mode pinyin. The input is the original Chinese text to practice (UTF-8), not pinyin; either a file or stdin is acceptable. No Typst, network, or login is required.

printf '%s' '你好' | cyeam pdf --mode pinyin -o practice.pdf
cyeam pdf words.txt --mode pinyin -o practice.pdf

• Reference website /tool/pinyin?xiezi=你好: A4 portrait, title "Look at Pinyin and Write Characters" at the top left, blank mi-zi grids below the pinyin prompts, no Chinese character answers shown.
• The question area starts at x=13 mm, y=20 mm, mi-zi grids are 11 × 11 mm, the pinyin area is 7 mm high, phrase spacing is 5 mm, and each line holds at most 17 grids; spaces, line breaks, punctuation, and other non-Chinese characters separate phrases and do not occupy grids. Phrases longer than 17 characters are automatically split.
• At the bottom, keep "Corrections:" and four horizontal lines at 255, 265, 275, and 285 mm. Long text automatically paginates, and each page repeats the title and correction area without silent truncation; grouping spacing may cause each page to hold fewer than 204 characters.
• Pinyin is generated by a local dictionary; pronunciations of polyphonic characters should be checked against context. Returns an error when there are no Chinese characters.
• The pinyin font is built in; the title and correction label use PDF Chinese font detection, requiring the system to provide an available Chinese font.--layout、--title Only used for arithmetic mode, cannot be mixed with pinyin mode.
• Same as other PDF modes,-o save the file, omit -o to return base64 JSON. Positional arguments are always file paths; to pass text directly, use stdin, or an existing cyeam pinyin sheet "你好" -o practice.pdf。

Method 1: File input (recommended for Agents)

Suitable for scenarios where a Markdown/HTML file already exists, or the Agent can first write the content to a temporary file. Structured argv tools, ordinary shell, Xiaoli's channel_send subsequent sends are all suitable for this method.

# 1. 先准备真实源文件，例如 /tmp/openclaw-install-guide.md
# 2. 再把源文件转成 PDF
cyeam pdf /tmp/openclaw-install-guide.md -o /tmp/openclaw-install-guide.pdf --pretty

Method 2: stdin input

Suitable for scenarios where the execution environment can write the body to the command's stdin. The body can be Markdown or HTML.

cyeam pdf -o /tmp/openclaw-install-guide.pdf --pretty

Note: the above form is correct only when stdin already provides content; if there is no stdin content, it will fail and prompt no content provided (stdin is empty)。

Method 3: shell pipe input

Suitable for human shells, or Agent/bash tools that explicitly support shell pipes.

cat /tmp/openclaw-install-guide.md | cyeam pdf -o /tmp/openclaw-install-guide.pdf --pretty
printf %s "# 标题\n\n正文" | cyeam pdf -o /tmp/out.pdf --pretty

If the current tool only accepts structured argv, does not provide stdin, and does not support shell pipes, please use Method 1: first create the source file, then execute cyeam pdf <source> -o <pdf> --pretty。

After generating the PDF for the user, continue to call the current channel's send tool (such as channel_send) to send the generated .pdf file.

Installation

# macOS Apple Silicon
curl -L https://github.com/mnhkahn/cyeam-cli/releases/latest/download/cyeam_Darwin_arm64.tar.gz | tar xz && chmod +x cyeam && sudo mv cyeam /usr/local/bin/

# macOS Intel
curl -L https://github.com/mnhkahn/cyeam-cli/releases/latest/download/cyeam_Darwin_x86_64.tar.gz | tar xz && chmod +x cyeam && sudo mv cyeam /usr/local/bin/

# Linux amd64
curl -L https://github.com/mnhkahn/cyeam-cli/releases/latest/download/cyeam_Linux_x86_64.tar.gz | tar xz && chmod +x cyeam && sudo mv cyeam /usr/local/bin/

Output

cyeam pdf README.md returns JSON:

{"ok":true,"data":"{\"pdf\":\"<base64>\"}"}

Add --out to save the file directly:

cyeam pdf README.md -o out.pdf --pretty
# saved: out.pdf

Without --pretty , output a JSON envelope:{"ok":true,"data":"saved: out.pdf\n"}

Notes

• Automatic format detection:.typ suffix is treated as Typst;.html/.htm suffix or content starting with <!DOCTYPE/<html is treated as HTML; the rest is treated as Markdown
• Purely local generation, using goldmark + gofpdf
• Supported layout elements: H1-H4 headings, paragraphs, bold/italic, inline code, code blocks, unordered/ordered lists, links, horizontal rules
• Markdown additionally supports ::: columns / ::: column multi-column extension
• Typst input requires typst
• Automatic pagination, A4 paper
• No login required