diff --git a/docs/blog/posts/2026-03-24-1.9-release/index.qmd b/docs/blog/posts/2026-03-24-1.9-release/index.qmd index d8f0589b3..cfd4a0e16 100644 --- a/docs/blog/posts/2026-03-24-1.9-release/index.qmd +++ b/docs/blog/posts/2026-03-24-1.9-release/index.qmd @@ -38,7 +38,7 @@ Quarto 1.9 brings substantial improvements to Typst output: - New options: `mathfont`, `codefont`, `linestretch`, `linkcolor`, `citecolor`, `filecolor`, `thanks`, and `abstract-title`. - [Theorem styling](/docs/output-formats/typst.qmd#theorems) with four appearance options: `simple`, `fancy`, `clouds`, or `rainbow`. -We'll have a detailed blog post on all the Typst improvements soon. +See [this blog post](/docs/blog/posts/2026-03-31-typst-books-and-more/index.qmd) for details on all the Typst improvements. ## PDF Accessibility (Experimental) diff --git a/docs/blog/posts/2026-03-31-typst-books-and-more/index.qmd b/docs/blog/posts/2026-03-31-typst-books-and-more/index.qmd new file mode 100644 index 000000000..63c7229bb --- /dev/null +++ b/docs/blog/posts/2026-03-31-typst-books-and-more/index.qmd @@ -0,0 +1,110 @@ +--- +title: Typst Books, Article Layout, and `typst-gather` +author: Gordon Woodhull +date: 2026-03-31 +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. diff --git a/docs/blog/posts/2026-03-31-typst-books-and-more/typst-article-2.png b/docs/blog/posts/2026-03-31-typst-books-and-more/typst-article-2.png new file mode 100644 index 000000000..9689203a6 Binary files /dev/null and b/docs/blog/posts/2026-03-31-typst-books-and-more/typst-article-2.png differ diff --git a/docs/blog/posts/2026-03-31-typst-books-and-more/typst-article-3.png b/docs/blog/posts/2026-03-31-typst-books-and-more/typst-article-3.png new file mode 100644 index 000000000..c5cdd354c Binary files /dev/null and b/docs/blog/posts/2026-03-31-typst-books-and-more/typst-article-3.png differ diff --git a/docs/blog/posts/2026-03-31-typst-books-and-more/typst-article-landscape.png b/docs/blog/posts/2026-03-31-typst-books-and-more/typst-article-landscape.png new file mode 100644 index 000000000..9cf46a646 Binary files /dev/null and b/docs/blog/posts/2026-03-31-typst-books-and-more/typst-article-landscape.png differ diff --git a/docs/blog/posts/2026-03-31-typst-books-and-more/typst-article.png b/docs/blog/posts/2026-03-31-typst-books-and-more/typst-article.png new file mode 100644 index 000000000..78d7d711e Binary files /dev/null and b/docs/blog/posts/2026-03-31-typst-books-and-more/typst-article.png differ diff --git a/docs/blog/posts/2026-03-31-typst-books-and-more/typst-book-1.png b/docs/blog/posts/2026-03-31-typst-books-and-more/typst-book-1.png new file mode 100644 index 000000000..38d59ceaa Binary files /dev/null and b/docs/blog/posts/2026-03-31-typst-books-and-more/typst-book-1.png differ diff --git a/docs/blog/posts/2026-03-31-typst-books-and-more/typst-book-2.png b/docs/blog/posts/2026-03-31-typst-books-and-more/typst-book-2.png new file mode 100644 index 000000000..25708930b Binary files /dev/null and b/docs/blog/posts/2026-03-31-typst-books-and-more/typst-book-2.png differ diff --git a/docs/blog/posts/2026-03-31-typst-books-and-more/typst-book-3.png b/docs/blog/posts/2026-03-31-typst-books-and-more/typst-book-3.png new file mode 100644 index 000000000..00c276032 Binary files /dev/null and b/docs/blog/posts/2026-03-31-typst-books-and-more/typst-book-3.png differ diff --git a/docs/blog/posts/2026-03-31-typst-books-and-more/typst-book-part-page.png b/docs/blog/posts/2026-03-31-typst-books-and-more/typst-book-part-page.png new file mode 100644 index 000000000..5aa9ea871 Binary files /dev/null and b/docs/blog/posts/2026-03-31-typst-books-and-more/typst-book-part-page.png differ