blog: typst books, article layout, and typst-gather

docs/blog/posts/2026-02-xx-typst-books-etc/index.qmd

@@ -0,0 +1,110 @@
+---
+title: Typst Books, Article Layout, and `typst-gather`
+author: Gordon Woodhull
+description: |
+  Quarto 1.9 adds Typst book projects, article margin layout via Marginalia, and offline package bundling with `typst-gather`.
+image: typst-article-landscape.png
+image-alt: A Typst article page showing code and a margin figure rendered with the Marginalia package
+lightbox: true
+---
+
+Typst is a lightning-fast typesetting system that provides a modern alternative to LaTeX.
+
+The Typst ecosystem is thriving, and Quarto 1.9 brings Typst much closer to feature parity with LaTeX:
+
+* Typst books
+* Article layout in Typst
+* Bundling of Typst packages for offline rendering
+
+## Typst books
+
+In Quarto 1.9, a project with type `book` and format `typst` is now rendered as a single document with multiple chapters and other book content.
+
+``` {.yaml filename="_quarto.yml"}
+project:
+  type: book
+
+book:
+  title: "My Book"
+  author: "Jane Doe"
+  chapters:
+    - index.qmd
+    - intro.qmd
+    - summary.qmd
+
+format: typst
+```
+
+::: {layout-ncol=4 group=book}
+![Part page](typst-book-part-page.png){fig-alt="A Typst book rendered with the orange-book extension, showing the part one page with a colored background and table of contents"}
+
+
+![Chapter page](typst-book-1.png){fig-alt="A Typst book rendered with the orange-book extension, showing the chapter one page with colored headers and sidebar navigation"}
+
+![Chapter content](typst-book-2.png){fig-alt="A Typst book rendered with the orange-book extension, showing the second page from chapter one with colored headers and sidebar navigation"}
+
+![Next chapter](typst-book-3.png){fig-alt="A Typst book rendered with the orange-book extension, showing the chapter two page with colored headers and sidebar navigation"}
+:::
+
+All book features previously available in the LaTeX format are now available in Typst:
+
+* Parts and Chapters
+* Appendices
+* Cross-references and chapter-based numbering
+* Table of Contents
+
+List-of-Figures and List-of-Tables support is [coming soon](https://github.com/quarto-dev/quarto-cli/issues/14081).
+
+The default Typst book uses the bundled Quarto [quarto-orange-book](https://github.com/quarto-ext/orange-book) extension, which uses [`typst-gather`](#typst-gather) to bundle the Typst [orange-book](https://typst.app/universe/package/orange-book) package. Orange-book provides a textbook-style layout with colored chapter headers and sidebars.
+
+The orange-book extension supports [brand.yml](/docs/authoring/brand.qmd) customization — it uses the `primary` color for chapter headers and sidebars, and the `medium` logo on the title page. The screenshots above were generated with this `_brand.yml`:
+
+``` {.yaml filename="_brand.yml"}
+color:
+  primary: "#F36619"
+  secondary: "#2E86AB"
+
+logo:
+  images:
+    test-logo:
+      path: logo.svg
+      alt: "Test Logo"
+  medium: test-logo
+```
+
+Since Typst books are implemented as Quarto [Format Extensions](/docs/extensions/formats.qmd), you can customize the appearance by creating your own extension. Typst partials define the overall book structure, while Lua filters handle the necessary AST transformations.
+
+## Article layout in Typst
+
+Also in Quarto 1.9, all [Article Layout](/docs/authoring/article-layout.qmd) features now work in Typst, via the Typst [Marginalia](https://typst.app/universe/package/marginalia/) package.
+
+Specifically:
+
+* Figures, tables, code listings, and equations can be placed in the margin using the `.column-margin` class or the `column: margin` code cell option.
+* You can also target specific output types with `fig-column: margin` or `tbl-column: margin`.
+* Figure, table, and code listing captions can be placed in the margin with `cap-location: margin` (or `fig-cap-location: margin` and `tbl-cap-location: margin` for specific types).
+* Footnotes and citations can be displayed in the margin with `reference-location: margin` and `citation-location: margin`. When margin citations are enabled, the bibliography is suppressed.
+* Asides (`.aside` class) place content in the margin without a footnote number.
+
+::: {layout-ncol=3 group=article}
+![Margin note and figure](typst-article.png){group="article" fig-alt="A page of a Typst article with a margin note and a margin figure using the Marginalia package"}
+
+![Margin captions](typst-article-2.png){group="article" fig-alt="A page of a Typst article using margin captions"}
+
+![Margin references](typst-article-3.png){group="article" fig-alt="A page of a Typst article using margin references"}
+:::
+
+::: {.callout-warning}
+## Books with article layout are functional, but need work
+You can combine book and article layout, but there are some layout quirks when combining the two. We'll work with the orange-book author to integrate Marginalia into the book template. 
+:::
+
+## `typst-gather`
+
+Quarto 1.9 automatically stages Typst packages — from your extensions, from Quarto's bundled extensions, and from Quarto itself — into the `.quarto/` cache directory before calling `typst compile`. This means Typst documents render offline without needing network access.
+
+To make this work, extension authors use the new [`typst-gather`](/docs/advanced/typst/typst-gather.qmd) tool, which scans their `.typ` files for `@preview` imports and downloads the packages into the extension directory. Authors run `quarto call typst-gather` and commit the results — users of the extension don't need to do anything.
+
+This means [Custom Typst Formats](/docs/output-formats/typst-custom.qmd#custom-formats) can depend on Typst packages without copying and pasting Typst code, making them simpler and easier to maintain.
+
+Both Typst books and article layout are built on `typst-gather` — orange-book depends on the Typst [orange-book](https://typst.app/universe/package/orange-book) package, and article layout depends on [Marginalia](https://typst.app/universe/package/marginalia/). As the Typst package ecosystem grows, we're excited to see what the community builds with Typst packages.