For AI agents: the complete documentation index is available at https://lazygophers.github.io/pamphlet/en/llms.txt, the full documentation bundle is available at https://lazygophers.github.io/pamphlet/en/llms-full.txt, and this page is available as Markdown at https://lazygophers.github.io/pamphlet/en/reference/frontmatter.md.
Pamphlet
  • English

      • Frontmatter reference

      There is no config file. All configuration lives in the frontmatter at the top of the source file — the part between the two --- lines.

      ---
spec: 1
title: Architecture plan
lang: en
toc:
  enable: true
  deep: 3
---

      The reasoning: one source file = one output, so configuration travels with the document and copying the document copies its settings. A separate config file adds a place for "the document is here, its settings are there" to drift apart.

      The fields it knows

      Six of them. Anything else reports a DOC-102 warning listing this set — never silently ignored, because silent ignoring lets you believe a setting took effect.

      FieldTypeDefaultMeaning
      specintegeromitted = no checkMinimum compiler syntax version this document needs
      titlestringthe first # headingThe output's <title>
      themestringdefaultWhich built-in theme to use
      langstringzh-CNThe output's <html lang="…">
      tocboolean or objectoffTable of contents
      enginesobject—Custom engines: an external command, source in on stdin, SVG out on stdout

      spec

      spec: 1

      Its role is singular: marking "this is a pamphlet source file". The current compiler supports version 1.

      A value higher than the compiler supports reports DOC-101 suggesting an upgrade. A non-integer reports DOC-103.

      It no longer triggers multi-parser behaviour — one parser is maintained. See the compatibility promise on the install page.

      title

      title: Architecture plan

      Without it, the search order is: the first # heading in the document → the literal string pamphlet.

      theme

      theme: editorial

      The built-in themes are sorted by document type. See Built-in themes for what each looks like.

      The --theme flag overrides this field — a one-off intent should beat the document's standing setting.

      An unknown name reports DOC-106 and falls back to default, still producing output: a wrong theme only affects how it looks; the content is fine.

      lang

      lang: en

      Written into the output's <html lang="…">. Defaults to zh-CN.

      It affects how screen readers pronounce text and how browsers break lines and spell-check; it changes no compiler behaviour.

      toc

      Shortest form:

      toc: true

      Full form:

      toc:
  enable: true
  deep: 3
  skipTabs: true
  position: side
      SubfieldTypeDefaultMeaning
      enablebooleanfalseNo ToC unless explicitly on
      deepinteger 1–62How deep headings are collected
      skipTabsbooleantrueSkip headings generated by tabs
      positiontop / sidesideA sticky side menu, or inline at the top of the document

      The ToC is purely static: a nested list of anchor links, zero JavaScript.

      The # heading does not appear in it — that is the document's own title. A deep outside 1–6 reports DOC-103.

      Why skipTabs defaults to true

      Tab panels are semantically several views of one topic; in a table of contents they read as separate chapters.

      But tab labels are real headings, for accessibility and deep linking, so they inevitably enter the document outline — which is why the ToC side needs this switch.

      Which side position puts it on

      The default is side: a sticky side menu, pure CSS, zero JavaScript. Below 60rem it falls back to the top of the document.

      To keep the ToC inline at the start of the body, scrolling away with the page:

      toc:
  position: top

      Anything other than those two values reports DOC-103 as an error — it does not silently fall back to the default, which would let you believe the value you wrote took effect.

      engines

      engines:
  myengine:
    langs: [foo]
    command: [mytool, --svg]
      Info

      command only The command path works today; http (a remote rendering service) is not built yet and earns a DOC-104 note.

      The full shape is described in Adding a custom diagram engine.

      Diagnostics point at the field

      Frontmatter diagnostics point at the line of the offending field, not vaguely at the ---:

      error[DOC-103] toc.deep 必须是 1 到 6 之间的整数
  --> plan.md:5:3
  |
5 |   deep: 9
  |   ^^^^