Supported Markdown Syntax¶

TeXSmith reads TMark: CommonMark plus the extension set every MkDocs site already loads, plus the four families that cover what print needs. This page is the quick tour; each row links to the page that explains the construct.

Core Markdown (Always On)¶

# Heading 1
## Heading 2
### Heading 3

**bold**, *italic*, ~~strikethrough~~, `inline code`

[Links](https://www.example.com) and ![images](assets/logo.svg)

> Blockquote text

- Unordered item
  - Nested item

1. Ordered item
2. Next item

Dividers:

---

All standard CommonMark constructs render as you would expect. A --- line is a divider: the web shows <hr>, and the paged writers emit \tsdivider, which the ts-typesetting fragment defines as a page break — a template redefines it at will. Inside a container — a block quote, a callout, a figure, a ::: div, a list item — the same --- emits \tsrule instead (<hr class="rule"> on the web): a separator, never a page break, because a page break there would tear the container in two.

Cheat sheet¶

Classes are the degradation classes of TMark: what a renderer other than TeXSmith shows for the same bytes.

Working with callouts¶

::: warning {title="LaTeX toolchain"}
Remember to install TeX Live, MiKTeX, or MacTeX before running `texsmith --build`.
:::

The PyMdownX spelling stays accepted indefinitely, because MkDocs Material renders it natively:

!!! warning "LaTeX toolchain"
    Remember to install TeX Live, MiKTeX, or MacTeX before running `texsmith --build`.

Callouts render as highlighted boxes in HTML and as tcolorbox blocks in the LaTeX output. See Admonitions.

Tables and definition lists¶

| Option | Description |
| ------ | ----------- |
| `--debug-ir` | Dumps the parsed IR next to the output |
| `--debug` | Shows full tracebacks |

Table: Selected command-line options. {#tbl:options}

Term
: Definition content

Both convert cleanly into LaTeX environments. For spans, grouped headers, footers and validation, see Tables.

Task lists and checkboxes¶

- [x] Validate MkDocs navigation
- [ ] Document template slots

Task lists render checkboxes in HTML. In LaTeX they become tstasklist entries with inline symbols.

Keyboard shortcuts¶

Use {keys}[ctrl+s] to save changes and {keys}[ctrl+shift+b] to build the docs.

The PyMdownX spelling ++ctrl+s++ is sugar for the same node and renders identically. Both reach the PDF as \tskeys{…}.

Embedding raw LaTeX¶

Use a latex raw fence when native LaTeX is required:

```latex raw
\begin{align}
E &= mc^2 \\
\nabla \cdot \vec{E} &= \frac{\rho}{\varepsilon_0}
\end{align}
```

TeXSmith passes the block straight to the LaTeX writer; the Typst and HTML writers ignore it. For inline adjustments, use the raw role:

The chapter ends here {raw latex}(\clearpage) before appendices.

/// latex … /// and {latex}[…] are the 0.6 spellings: still parsed, now deprecated. See Migrating to TMark.

Includes¶

{include}(includes/built-in-tasks.md)

The file is parsed as TMark and spliced into the document, so nested fences are safe and relative paths inside it are rebased. To pull a code sample from a file without inlining it, put include= on the fence:

```python include="examples/code/bubble_sort.py"
```

The PyMdownX snippet syntax --8<-- "file" is accepted as deprecated sugar. Its marker is -{2,}8<-{2,}, so any dash count on either side is the same spelling (---8<--- included), and a leading ; disables the line. See Code.

Foreign directives¶

[TOC] and a dotted pkg.module line — mkdocstrings' syntax, its options in the indented YAML that follows — are directives for a processor other than TMark. Both are kept verbatim, and both are dropped by the paged writers: the printed table of contents is press.toc, and an API reference has no print form. A dotted directive raises the hint directive-foreign so a print document does not lose a block without notice. See Admonitions.

When you need more¶

• tmark check FILE parses, resolves and lints a document; --strict turns warnings into failures.
• tmark lint --fix FILE rewrites deprecated spellings.
• tmark parse FILE prints the intermediate representation as JSON — the ground truth about what the parser read.
• If a feature relies on a third-party executable (Mermaid to PDF, draw.io export), make sure the binary is available on the build worker before running texsmith --build.