Version0.2.1Verifiednot yet verifiedLicenseBSD-3-Clause

sigil-doc

A programmable document language for Sigil

Report a bug or suggest a feature
Clone

git clone https://git.usesigil.org/sigil/sigil-doc.git

Readme

sigil-doc

sigil-doc is Sigil's programmable document language. A document is an ordinary Sigil program with a prose-oriented reader:

#lang sigil/doc

@(define-syntax strong
   (syntax-rules () ((_ child) (em child))))

@article ["A Small Document" "An Author"]

@section ["First Section"]

@p: Prose can contain @strong{ordinary author macros}.

@end section
@end article

Commands are ordinary imported or manuscript-local bindings. Everything in [...] is read and evaluated as standard Sigil, including multiline forms, keywords, macros, and computed values. Top-level @(...) forms can import modules or define functions and macros; @(...) inside a document computes a node or proper list of nodes at that position.

Every command supports the same body notations:

@name[...] { ... }        balanced body
@name[...]                named multiline body
  ...
@end name
@name[...]: ...           remainder of the physical line
@name[...] {}             explicit empty body

Horizontal whitespace around arguments and braces is cosmetic, indentation is never semantic, and whitespace immediately inside a body is delimiter padding. Inline commands use braces; named and line bodies are available only at a block boundary. @code{identifier} is inline code; @code["sigil"]{...} is a language-labelled block, and @code[#f]{...} is an unlabelled block. Named and colon @code bodies are also blocks. Subject source inside these forms is data and is not executed during document authoring.

Executable examples, their expectations and hidden checks are described in `docs/examples.md`.

Read the rest

Evaluation binds the resulting semantic value as document. The package includes backend-neutral model/traversal/publication modules, static HTML fragments, and a backend-neutral print adapter with a Typst source backend. Press consumes the HTML fragments for sites; sigil-doc invokes an existing typesetter for PDF rather than implementing typography or pagination.

Build the current two-chapter Practical Sigil print edition with:

guix shell typst poppler -- \
  tools/build-practical-sigil-pdf.sh build/practical-sigil.pdf

The .typ source is retained beside the deterministic, tagged PDF. See `docs/print-backend.md` for the backend decision, reproducibility contract, font strategy, and long-code wrapping rule.

Print customization is ordinary checked-in Sigil code. The publication policy in (sigil doc print) controls numbering, chapter authors, contents, chapter starts, and running-header content. The immutable typst-theme in (sigil doc render typst) controls paper, margins, fonts, typography, colors, code treatment, headers, and page-number placement. Practical Sigil keeps these decisions in book/practical-sigil/book.sgl and theme.sgl, separate from its semantic .sgd chapters. The default edition remains byte-compatible with D6; the same configuration also demonstrates a distinct A5 compact-study edition.

A distinct @pre form for non-code preformatted material is intentionally deferred until a real manuscript establishes its semantic model; it is not an alias for code in D2.

The chapter-sized pressure fixture is `test/fixtures/practical-sigil-chapter.sgd`. With a compiler that supports alternate readers, evaluate it with:

sigil -L src -L test eval -f test/fixtures/practical-sigil-chapter.sgd

Inspecting a document without running it

(sigil doc inspect) returns a manuscript's raw command tree with exact spans and evaluates no author code, so a program can learn a document's structure without trusting it. The ordinary reader path returns lowered syntax, which must be evaluated to yield structure; the inspection surface exists for consumers that cannot do that, such as an indexer pointed at untrusted or half-written documents.

sigil -L src -L test eval -f test/sd-p4-witness-probe.sgl

See `docs/passive-parse-api.md` for the node and span representation, the guarantees, and the explicit non-guarantees.

The root container, and the two languages

#lang sigil/doc admits exactly one @article at top level — the generic standalone document. The book/print genre is a sibling language, #lang sigil/doc/book, which admits exactly one @chapter. That is ruling D8: the base language stays generic, and genres are languages rather than extra roots in the base.

Root policy is a value rather than a constant, so both of those languages are the same parser with a different profile, and a language in another package can name its own roots without forking the grammar or the location machinery:

(import (sigil doc reader))

(define folio-profile (make-document-profile "folio/doc" '(note project) 'one-or-more))
(parse-document-parts-with-profile folio-profile source source-name header-end)

The root-policy diagnostics are derived from the profile, so each language reports its own name and its own roots. See `docs/root-profiles.md` for the profile fields, the two shipped languages, what a profile deliberately does not vary, and why the root comes from the #lang line rather than from an import.

Releases

v0.2.1 — latest by version, released 17 Nov 2026

All releases — 6 tags in this repository.

Source

Browse the latest source

One page per file, and every line has a permalink.

Recent commitsAtom
17 Novcommit
23 Octcommit
3 Sepcommit
3 Sepcommit
24 Augcommit
23 Augcommit
23 Augcommit
23 Augcommit
23 Augcommit
23 Augcommit
23 Augcommit
23 Augcommit
23 Augcommit
22 Augcommit
22 Augcommit
22 Augcommit
22 Augcommit

chore: 0.1.4

0b7c5cac

22 Augcommit
12 Augcommit
12 Augcommit

The last 20 commits keep a page here. Everything older lives in the clone.