typst article layout

docs/advanced/typst/typst-gather.qmd

@@ -0,0 +1,138 @@
+---
+title: "Gathering Typst Packages"
+---
+
+When developing a custom Typst format that uses packages from the Typst preview namespace (e.g., `@preview/marginalia`), you can bundle those packages with your extension for offline use. The `quarto call typst-gather` command automates this process.
+
+## Basic Usage
+
+From your extension directory, run:
+
+``` {.bash filename="Terminal"}
+quarto call typst-gather
+```
+
+The command:
+
+1. Detects your extension's `.typ` files from `_extension.yml`
+2. Scans them for `@preview` package imports
+3. Downloads packages into your extension directory at `typst/packages/` (e.g., `_extensions/myformat/typst/packages/`)
+
+## Auto-Detection
+
+When run without a configuration file, `typst-gather` reads your `_extension.yml` to find Typst files:
+
+``` {.yaml filename="_extension.yml"}
+contributes:
+  formats:
+    typst:
+      template: template.typ
+      template-partials:
+        - typst-template.typ
+        - typst-show.typ
+```
+
+The `template` and `template-partials` files are scanned for imports like:
+
+```typ
+#import "@preview/marginalia:0.3.1": note, wideblock
+```
+
+## Configuration File
+
+For more control, create a `typst-gather.toml` configuration file:
+
+``` {.bash filename="Terminal"}
+quarto call typst-gather --init-config
+```
+
+This generates a starter configuration based on your extension:
+
+``` {.toml filename="typst-gather.toml"}
+# typst-gather configuration
+# Run: quarto call typst-gather
+
+rootdir = "_extensions/myformat"
+destination = "typst/packages"
+
+discover = ["typst-template.typ", "typst-show.typ"]
+
+# Preview packages are auto-discovered from imports.
+# Uncomment to pin specific versions:
+# [preview]
+# marginalia = "0.3.1"
+# cetz = "0.4.1"
+
+# Local packages (@local namespace) must be configured manually.
+# [local]
+# my-pkg = "/path/to/my-pkg"
+```
+
+### Configuration Options
+
+| Option | Description |
+|--------|-------------|
+| `rootdir` | Extension directory (e.g., `_extensions/myformat`) |
+| `destination` | Where to download packages, relative to `rootdir` (default: `typst/packages`) |
+| `discover` | `.typ` files to scan for imports, relative to `rootdir` |
+
+### Pinning Versions
+
+By default, packages are discovered from your import statements. To pin specific versions, add a `[preview]` section:
+
+``` {.toml filename="typst-gather.toml"}
+[preview]
+marginalia = "0.3.1"
+cetz = "0.4.1"
+```
+
+### Local Packages
+
+If your templates use `@local` packages, configure their paths in the `[local]` section:
+
+``` {.toml filename="typst-gather.toml"}
+[local]
+my-utils = "/path/to/my-utils"
+```
+
+## Package Staging
+
+When rendering a Typst document, Quarto automatically stages packages before calling `typst compile`:
+
+1. **Built-in packages** from Quarto's resources are staged first (e.g., Marginalia for article layouts)
+2. **Extension packages** from `_extensions/<ext>/typst/packages/` are merged in, overriding any built-in packages with the same name
+
+Packages are staged to `.quarto/typst/packages/` in the project directory, then passed to Typst via:
+
+- `--package-path` for `@local` packages
+- `--package-cache-path` for `@preview` packages
+
+### Package Directory Structure
+
+The staged directory follows Typst's package layout:
+
+```
+.quarto/typst/packages/
+├── preview/
+│   └── marginalia/
+│       └── 0.3.1/
+│           ├── lib.typ
+│           └── typst.toml
+└── local/
+    └── my-pkg/
+        └── 0.1.0/
+            └── ...
+```
+
+This means bundled packages work offline without requiring network access during rendering.
+
+## Workflow
+
+A typical workflow for bundling packages:
+
+1. Develop your custom format using Typst packages
+2. Run `quarto call typst-gather` to download dependencies
+3. Commit the `typst/packages/` directory with your extension
+4. Users installing your extension get the bundled packages
+
+This ensures your extension works offline and with consistent package versions.

docs/authoring/article-layout.qmd

@@ -19,7 +19,7 @@ Quarto supports a variety of page layout options that enable you to author conte
 
 Quarto uses the concept of columns to describe page layout (e.g. the "body" column, the "margin" column, etc.). Below we'll describe how to arrange content into these columns. If you need to adjust the widths of the columns, see [Page Layout - Grid Customization](/docs/output-formats/page-layout.qmd#grid-customization).
 
-All of the layout capabilities described in this document work for HTML output and many work for PDF and LaTeX output. For details about the PDF / LaTeX output, see [PDF/LaTeX Layout].
+All of the layout capabilities described in this document work for HTML and Typst output. Many also work for PDF and LaTeX output, though with some differences. See [Typst Layout] and [PDF/LaTeX Layout] for format-specific details.
 
 ## Body Column
 
@@ -483,6 +483,27 @@ This enables non-breaking code to overflow into the margin without cosmetic issu
 
 You can disable this treatment by setting the following `code-block-border-left: false` in your document front matter.
 
+## Typst Layout {#typst-layout data-link="Typst Layout"}
+
+Typst output supports the layout capabilities described in this document via the [Marginalia](https://typst.app/universe/package/marginalia) package.
+
+### Page Geometry
+
+When you use margin content in a Typst document, Quarto automatically calculates appropriate page geometry based on your `papersize` setting. The geometry creates a narrower body column and a margin column for notes and figures.
+
+You can customize the column widths using the `grid` option:
+
+``` yaml
+format:
+  typst:
+    grid:
+      margin-width: 2in
+      body-width: 4in
+      gutter-width: 0.25in
+```
+
+For fine-grained control over margin placement, Typst also provides the `margin-geometry` option which directly configures the underlying Marginalia package. See [Typst Basics - Article Layout](/docs/output-formats/typst.qmd#article-layout) for details.
+
 ## Landscape mode
 
 In `docx`, `pdf` and `typst` formats, you can set portions of the document to landscape mode by wrapping the content around a fenced div with class `landscape`:

docs/output-formats/page-layout.qmd

@@ -113,6 +113,12 @@ There are four variables to control the four components of the layout: the sideb
 
 The rest of this section describes these components, and their default values, as well as how to customize them either with YAML or SCSS  variables. You can also find [Additional Examples](#more-examples) of customization in action.
 
+::: {.callout-note}
+## Typst Grid Options
+
+For Typst output, only `margin-width`, `body-width`, and `gutter-width` apply (there is no sidebar in PDF documents). Typst also provides a `margin-geometry` option for fine-grained control over margin placement. See [Typst Basics - Article Layout](/docs/output-formats/typst.qmd#article-layout) for details.
+:::
+
 ### HTML Page Layout
 
 Quarto HTML documents are arranged in a structure composed of a sidebar on the left, the body of the document, the margin of the document on the right, and the space between these elements, known as gutters. This is illustrated below:

docs/output-formats/typst-custom.qmd

@@ -78,3 +78,17 @@ contributes:
 Use the [source code](https://github.com/quarto-dev/quarto-cli/blob/main/src/resources/formats/typst/pandoc/quarto/template.typ) of the default template as a starting point for your `template.typ`. Note that you can call all of the template partials provided by Quarto (e.g. `biblio.typ()` or `notes.typ()`) from within your custom template implementation.
 
 The [AMS](https://github.com/quarto-ext/typst-templates/tree/main/ams) format provides an example of redefining the main template (in that case, it is to prevent automatic bibliography processing by Quarto in deference to the built-in handling of the Typst AMS template).
+
+## Bundling Typst Packages
+
+If your custom format uses packages from the Typst preview namespace (e.g., `@preview/cetz`), you can bundle them with your extension for offline use. The `quarto call typst-gather` command scans your template files for `@preview` imports and downloads the packages.
+
+From your extension directory, run:
+
+``` {.bash filename="Terminal"}
+quarto call typst-gather
+```
+
+The command auto-detects your `.typ` files from `_extension.yml` and downloads packages into your extension directory (e.g., `_extensions/myformat/typst/packages/`).
+
+For configuration options and advanced usage, see [Gathering Typst Packages](/docs/advanced/typst/typst-gather.qmd).

docs/output-formats/typst.qmd

@@ -53,8 +53,6 @@ Since Typst is under active development, there are still some limitations to Qua
 
 -   The default size of images may not reflect the behavior you are used to in other output formats. This is a problem that Typst, pandoc and Quarto are actively working to fix. In the meantime, you can manually [specify image widths](/docs/authoring/figures.qmd#figure-sizing).
 
--   Advanced page layout (e.g. using the `.column-*` classes as explained in [Article Layout](/docs/authoring/article-layout.qmd)) is not implemented.
-
 -   Various other small things might not yet be implemented. Please [let us know](https://github.com/quarto-dev/quarto-cli/issues/new/choose) if you see things that could use improvement!
 
 ## Page Layout
@@ -142,6 +140,66 @@ You can read more about specifying the numbering schema in the [Typst documentat
 
 {{< include /docs/output-formats/_code-annotation.md >}}
 
+## Article Layout {#article-layout}
+
+Quarto's Typst format supports Tufte-style article layouts with margin content, full-width figures, and sidenotes, via the [Marginalia](https://typst.app/universe/package/marginalia) package. See [Article Layout](/docs/authoring/article-layout.qmd) for the complete guide to column classes and margin content.
+
+### Grid Customization
+
+You can customize the width of the margin and body columns using the `grid` option:
+
+``` yaml
+format:
+  typst:
+    grid:
+      margin-width: 2in
+      body-width: 4in
+      gutter-width: 0.25in
+```
+
+| Option         | Description                                      |
+|----------------|--------------------------------------------------|
+| `margin-width` | Width of the margin note column                  |
+| `body-width`   | Width of the main text column                    |
+| `gutter-width` | Gap between body text and margin                 |
+
+: Grid options for Typst {tbl-colwidths="[30,70]"}
+
+Note: `sidebar-width` does not apply to Typst output (there is no sidebar in PDF documents).
+
+For HTML grid customization, see [Page Layout - Grid Customization](/docs/output-formats/page-layout.qmd#grid-customization).
+
+### Margin Geometry
+
+For fine-grained control over margin layout, use the `margin-geometry` option. This directly configures the underlying [Marginalia](https://typst.app/universe/package/marginalia) package.
+
+``` yaml
+format:
+  typst:
+    margin-geometry:
+      outer:
+        far: 5mm
+        width: 2in
+        separation: 0.25in
+      inner:
+        far: 5mm
+        width: 0in
+        separation: 0in
+      clearance: 8pt
+```
+
+| Option             | Description                                                |
+|--------------------|------------------------------------------------------------|
+| `outer.far`        | Distance from outer page edge to wideblock boundary        |
+| `outer.width`      | Width of the outer margin note column                      |
+| `outer.separation` | Gap between outer margin and body text                     |
+| `inner.*`          | Same options for inner margin (left side on recto pages)   |
+| `clearance`        | Minimum vertical spacing between margin notes (default 12pt)|
+
+: Margin geometry options {tbl-colwidths="[30,70]"}
+
+Quarto computes margin geometry based on `papersize`, using proportions from [Marginalia's](https://typst.app/universe/package/marginalia) A4 example.
+
 ## Bibliography
 
 {{< include _typst-citations.md >}}