typst-author

Files (59)

• ATTRIBUTION.md
• SKILL.md
• 0.1.0.md · docs/changelog/
• 0.10.0.md · docs/changelog/
• 0.11.0.md · docs/changelog/
• 0.11.1.md · docs/changelog/
• 0.12.0.md · docs/changelog/
• 0.13.0.md · docs/changelog/
• 0.13.1.md · docs/changelog/
• 0.14.0.md · docs/changelog/
• 0.14.1.md · docs/changelog/
• 0.14.2.md · docs/changelog/
• 0.15.0.md · docs/changelog/
• 0.2.0.md · docs/changelog/
• 0.3.0.md · docs/changelog/
• 0.4.0.md · docs/changelog/
• 0.5.0.md · docs/changelog/
• 0.6.0.md · docs/changelog/
• 0.7.0.md · docs/changelog/
• 0.8.0.md · docs/changelog/
• 0.9.0.md · docs/changelog/
• earlier.md · docs/changelog/
• index.md · docs/changelog/
• utils.md · docs/changelog/
• accessibility.md · docs/guides/
• for-latex-users.md · docs/guides/
• index.md · docs/guides/
• page-setup.md · docs/guides/
• tables.md · docs/guides/
• index.md · docs/
• overview.md · docs/
• bundle.md · docs/reference/export/
• html.md · docs/reference/export/
• index.md · docs/reference/export/
• pdf.md · docs/reference/export/
• png.md · docs/reference/export/
• svg.md · docs/reference/export/
• index.md · docs/reference/
• context.md · docs/reference/language/
• index.md · docs/reference/language/
• scripting.md · docs/reference/language/
• styling.md · docs/reference/language/
• syntax.md · docs/reference/language/
• data-loading.md · docs/reference/library/
• emoji.md · docs/reference/library/
• foundations.md · docs/reference/library/
• index.md · docs/reference/library/
• introspection.md · docs/reference/library/
• layout.md · docs/reference/library/
• math.md · docs/reference/library/
• model.md · docs/reference/library/
• sym.md · docs/reference/library/
• text.md · docs/reference/library/
• visualize.md · docs/reference/library/
• 1-writing.md · docs/tutorial/
• 2-formatting.md · docs/tutorial/
• 3-advanced.md · docs/tutorial/
• 4-template.md · docs/tutorial/
• index.md · docs/tutorial/

SKILL.md (first lines)

# typst-author skill

## Overview

This skill helps agents generate, edit, and reason about Typst documents. It provides quick‑start examples, detailed workflows, and links to the Typst documentation (overview, guides, tutorials, reference).

## Minimal document example

```typst
#set document(title: "My Document", author: "Author Name")
#set page(numbering: "1")
#set text(lang: "en")

// Enable paragraph justification and character-level justification
#set par(
  justify: true,
  justification-limits: (
    tracking: (min: -0.012em, max: 0.012em),
    spacing: (min: 75%, max: 120%),
  )
)

#title[My Document]

= Heading 1

This is a paragraph in Typst.

== Heading 2

#lorem(50)
```

## Workflows

- **Creating a new Typst project**:
  - Use the "Minimal document example" above as a starting point.
  - Skim the tutorial for the basics ([docs/tutorial/1-writing.md](docs/tutorial/1-writing.md)), then create the `.typ` file(s).
  - After each `.typ` edit, follow the post-edit formatting checks below when `typstyle` is available.
- **Editing existing content**:
  - Locate the target text and apply changes; confirm syntax against the reference when needed ([docs/reference/index.md](docs/reference/index.md)).
  - After each modified `.typ` file, follow the post-edit formatting checks below.
- **Formatting & styling**:
  - Consult the styling guide ([docs/reference/language/styling.md](docs/reference/language/styling.md)) for `set rule`, `show rule`, selectors, and transformations.
  - Preserve visual consistency: new layouts, figures, tables, and drawings must reuse the document's existing fonts, colors, and typographic hierarchy (unless instructed otherwise). Internal consistency should be maintained (same function → same size and color).

## Documentation

- **Orientation**: `docs/overview.md` for a high-level introduction, `docs/reference/index.md` for the reference structure, and `docs/tutorial/index.md` for the tutorial sequence.
- **Tutorial**: `docs/tutorial/1-writing.md` for basic markup, functions, labels, citations, and math; `docs/tutorial/2-formatting.md` for set rules, page setup, headings, and text formatting; `docs/tutorial/3-advanced.md` for templates, show rules, and more complex styling; `docs/tutorial/4-template.md` for reusable templates and packages.
- **Language syntax**: `docs/reference/language/syntax.md` for markup/math/code modes, comments, escapes, and identifiers.
- **Language scripting**: `docs/reference/language/scripting.md` for expressions, code/content blocks, bindings, conditionals, loops, fields, methods, modules, packages, and operators.
- **Language styling**: `docs/reference/language/styling.md` for set rules, show rules, selectors, and transformations.
- **Language context**: `docs/reference/language/context.md` for style context, location context, nested contexts, and compiler iterations.
- **Foundations**: `docs/reference/library/foundations.md` for basic types/functions, `std`, `sys.version`, and `sys.inputs`.
- **Document model**: `docs/reference/library/model.md` for headings, figures, bibliography, citations, references, numbering, outlines, lists, tables, and document structure.
- **Layout**: `docs/reference/library/layout.md` for arranging elements on the page: page, block, box, grid, columns, alignment, spacing, transforms, and measurement.
- **Text**: `docs/reference/library/text.md` for text styling and the `text` function.
- **Math**: `docs/reference/library/math.md` for math syntax, symbols, equations, alignment, fonts, accessibility, and math functions.
- **Drawing and media**: `docs/reference/library/visualize.md` for shapes, image/graphics primitives, color, gradients, strokes, and visual accessibility.
- **Introspection**: `docs/reference/library/introspection.md` for counters, state, locations, `query`, and document-aware generated content.
- **Data loading**: `docs/reference/library/data-loading.md` for loading and encoding external data such as CSV, JSON, TOML, YAML, XML, CBOR, and raw files.
- **Symbols and emoji**: `docs/reference/library/sym.md` for named symbols and shorthands; `docs/reference/library/emoji.md` for emoji.
- **Export formats**: `docs/reference/export/pdf.md` for PDF standards and PDF-specific features; `docs/reference/export/html.md` for HTML export and typed HTML; `docs/reference/export/bundle.md` for multi-output bundles and assets; `docs/reference/export/svg.md` and `docs/reference/export/png.md` for image exports.
- **Guides**: `docs/guides/page-setup.md` for pages, margins, headers, footers, numbering, and columns; `docs/guides/tables.md` for semantic tables and table styling; `docs/guides/accessibility.md` for semantic structure, alt text, language, PDF accessibility, and export considerations; `docs/guides/for-latex-users.md` for LaTeX-to-Typst translation.

## Detailed instructions

1. **PRIORITY: Trust local documentation**. Your internal training data regarding Typst may be outdated or hallucinated. Always verify function names, parameters, and syntax against the local Typst 0.15.0 `docs/` folder before generating code.
2. **Read the relevant documentation** using local file search and open tools on the paths above.
3. **Use local docs for syntax and reference questions**. Verify syntax, function names, parameters, and reference behavior from the bundled docs. Run a minimal Typst probe only when runtime or evaluation behavior remains unclear after checking the docs.
4. **Generate or modify the `.typ` source** according to the user's request.
5. **Run the post-edit formatting checks below** for every `.typ` file you created or edited in that pass.
6. **Validate** with `typst compile` after the formatting decision is complete when you created or edited `.typ` files, or when the user explicitly asks for verification (if tool access is allowed).
7. **Summarize touched files and outcomes**. Provide full `.typ` content only when the user requests it or when direct editing is not possible, and optionally include a rendered preview (PDF/HTML).

### Probing uncertain behavior

- Use a probe when the bundled docs do not settle runtime or evaluation behavior.
- Model the case with Typst scripting as described in [docs/reference/language/scripting.md](docs/reference/language/scripting.md).
- When a probe is necessary, prefer a fileless expression probe with `typst eval` instead of creating scratch `.typ` files. See [docs/reference/library/foundations.md](docs/reference/library/foundations.md) for system values and [docs/reference/library/introspection.md](docs/reference/library/introspection.md) for contextual document queries.
- Example: `typst eval '1 + 2'`

### Post-edit formatting checks

1. **Check whether `typstyle` is available** with `command -v typstyle`. If it is unavailable, skip the remaining formatting checks.
2. **After each `.typ` file modification, run `typstyle --check <file>`** for the file you just created or edited.
3. **If `typstyle --check` fails, inspect the formatter changes with `typstyle --diff <file>`** before deciding what to do.
4. **Apply formatting with `typstyle -i <file>`** only when the formatter changes are limited to a newly created file or to code you created or edited in the current task.
5. **Stop and ask the user when formatting would change untouched pre-existing code**. If the diff reaches outside your own edits, or if you cannot confidently prove that every formatter change is limited to your edits, ask instead of formatting.

## Quick syntax reference

### Critical distinctions

- **Arrays**: `(item1, item2)` (parentheses). See [docs/reference/library/foundations.md](docs/reference/library/foundations.md).
- **Dictionaries**: `(key: value, key2: value2)` (parentheses with colons). See [docs/reference/library/foundations.md](docs/reference/library/foundations.md).
- **Content blocks**: `[markup content]` (square brackets). See [docs/reference/language/scripting.md](docs/reference/language/scripting.md).
- **NO tuples**: Typst only has arrays.

### Hash usage (markup vs code)

- Use `#` to start a code expression inside markup or content blocks; it disambiguates code from text. This is required for content-producing function calls and field access in markup: `#figure[...]`, `#image("file.png")`, `text(...)[#numbering(...)]`.
- Do not use `#` inside code contexts (argument lists, code blocks, show-rule bodies). Example: `#figure(image("file.png"))` (no `#` before `image`).
- Reference: [docs/reference/language/scripting.md](docs/reference/language/scripting.md), [docs/tutorial/1-writing.md](docs/tutorial/1-writing.md)

```typst
// Incorrect (missing # inside content block)
text(...)[(numbering(...))]

// Correct
text(...)[(#numbering(...))]
```

### Styling rules: set vs show

- `set`: Set rule to configure optional parameters on element functions (style defaults scoped to the current block or file).
- `show`: Show rule to target selected elements and apply a set rule or transform/replace the element output.
- Use `set` for common styling; use `show` for selective or structural changes (e.g., `heading.where(level: 1)`, labels, text, regex).

From Optima-CityU/LLM4AD_Next, BSD-3-Clause.

More from Optima-CityU/LLM4AD_Next