docs: add a documentation website under docs/

.github/workflows/pages.yml

@@ -0,0 +1,40 @@
+name: Pages
+
+# The documentation website under docs/ is what this repository serves from
+# GitHub Pages. A pull request renders it as a check, from its own head.
+# Publishing happens at a release, through the Release workflow, or on a manual
+# dispatch here.
+on:
+  pull_request:
+    paths:
+      - "docs/**"
+      - "_extensions/**"
+      - "CHANGELOG.md"
+      - ".github/workflows/pages.yml"
+  workflow_dispatch:
+    inputs:
+      use-main-as-release:
+        type: boolean
+        description: "Render from the default branch instead of the latest version tag"
+        default: false
+      quarto:
+        type: choice
+        description: "Quarto version"
+        default: "release"
+        options:
+          - "release"
+          - "pre-release"
+
+permissions:
+  contents: read
+
+jobs:
+  pages:
+    uses: mcanouil/quarto-workflows/.github/workflows/pages.yml@main
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    with:
+      use-main-as-release: ${{ inputs.use-main-as-release || false }}
+      quarto: ${{ inputs.quarto || 'release' }}

.github/workflows/quarto-extensions-updates.yml

@@ -0,0 +1,23 @@
+name: Quarto Extensions Updates
+
+# Keeps the documentation website's own dependencies current: atelier, iconify,
+# and gitlink under docs/_extensions/.
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: 00 12 1 * *
+
+permissions:
+  contents: read
+
+jobs:
+  updates:
+    uses: mcanouil/quarto-workflows/.github/workflows/quarto-extensions-updates.yml@main
+    secrets: inherit
+    permissions:
+      contents: write
+      pull-requests: write
+    with:
+      gh-app-id: ${{ vars.APP_ID }}
+      scan-directories: |
+        docs

.gitignore

@@ -9,3 +9,5 @@ docs/api/*.qmd
 /.luarc.json
 /example.typ
 /example-typst.pdf
+/.quarto/
+**/*.quarto_ipynb

.quartoignore

@@ -0,0 +1,11 @@
+# Files kept out of a project created by `quarto use template`.
+# Quarto already excludes dot files, README.md, CHANGELOG.md, LICENSE,
+# COPYING.md, COPYRIGHT, CLAUDE.md, and AGENTS.md, so only what it misses
+# is listed here.
+
+# The documentation website. Quarto's built-in `_extensions` exclude matches
+# the repository root only, so docs/_extensions/mcanouil/ is not covered by it.
+docs
+
+# The repository's own citation metadata, not the new project's.
+CITATION.cff

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+### Documentation
+
+- docs: Add a documentation website under `docs/`, built on the `atelier` project type and published to <https://m.canouil.dev/quarto-code-window/>, framed by the extension itself.
+- docs: Record that the filter claims code blocks at `pre-quarto`, which prevents `typst-render` from seeing its own `{typst}` blocks and double-decorates alongside `language-cell-decorator`.
+- docs: Trim `README.md` to a landing page pointing at the website.
+- docs: Add the Pages workflow, which renders `docs/` on pull requests and deploys it from the release tag.
+- docs: Add the Quarto Extensions Updates workflow, scanning `docs` for the website's own dependencies.
+
 ## 1.3.0 (2026-07-22)
 
 ### New Features

README.md

@@ -1,8 +1,6 @@
 # Code Window Extension for Quarto
 
-A Quarto extension that adds window-style decorations to code blocks.
-Three styles are available: macOS traffic lights, Windows title bar buttons, or a plain filename bar.
-Supports HTML, Reveal.js, and Typst formats.
+`code-window` is an extension for Quarto that frames code blocks as application windows: a title bar with the filename, traffic lights or title-bar buttons, and optional folding.
 
 ## Installation
 
@@ -11,191 +9,14 @@ quarto add mcanouil/quarto-code-window@1.3.0
 ```
 
 This will install the extension under the `_extensions` subdirectory.
-If you are using version control, you will want to check in this directory.
+If you're using version control, you will want to check in this directory.
 
-## Usage
+## Documentation
 
-Add the filter to your document or project:
+The full documentation lives at <https://m.canouil.dev/quarto-code-window/>: every option and per-block attribute, the three window styles, the folding, and the Typst hot-fixes.
 
-```yaml
-filters:
-  - at: pre-quarto
-    path: code-window
-```
-
-### Explicit Filename
-
-Code blocks with a `filename` attribute display a window header with the filename.
-The decoration style depends on the `style` option.
-
-````markdown
-```{.python filename="fibonacci.py"}
-def fibonacci(n: int) -> int:
-    if n <= 1:
-        return n
-    return fibonacci(n - 1) + fibonacci(n - 2)
-```
-````
-
-### Auto-Generated Filename
-
-By default, code blocks without an explicit filename automatically show the language name in small-caps styling.
-
-````markdown
-```python
-print("Hello, World!")
-```
-````
-
-## Configuration
-
-Configure the extension in your document's YAML front matter:
-
-```yaml
-extensions:
-  code-window:
-    enabled: true
-    auto-filename: true
-    style: "macos"
-    wrapper: "code-window"
-    collapse: false
-    lines-label: true
-    hotfix:
-      code-annotations: true
-      skylighting: true
-      typst-title: true
-```
-
-### Options
-
-| Option          | Type           | Default         | Description                                                                                              |
-| --------------- | -------------- | --------------- | -------------------------------------------------------------------------------------------------------- |
-| `enabled`       | boolean        | `true`          | Enable or disable the code-window filter.                                                                |
-| `auto-filename` | boolean        | `true`          | Automatically generate filename labels from the code block language, and frame no-language / unknown-language blocks like highlighted cells (a no-language block is labelled `default`; an unknown language keeps its original token). Set to `false` to disable globally. |
-| `style`         | string         | `"macos"`       | Window decoration style: `"macos"`, `"windows"`, or `"default"`.                                         |
-| `wrapper`       | string         | `"code-window"` | Typst wrapper function name for code-window rendering.                                                   |
-| `collapse`      | boolean/string | `false`         | Wrap every code window in a `<details>` element (HTML). Accepts `false`, `true`, `"open"`, `"closed"`.   |
-| `lines-label`   | boolean        | `true`          | Render a small chip next to the filename showing the highlighted-line spec.                              |
-
-### Hotfix Options
-
-These options are **temporary** and will be removed in a future version (see [Temporary hot-fixes](#temporary-hot-fixes-typst)).
-
-Each hotfix value can be a simple boolean or a map with `enabled` and `quarto-version` keys for per-hotfix version thresholds.
-
-| Option                    | Type         | Default | Description                                                                                |
-| ------------------------- | ------------ | ------- | ------------------------------------------------------------------------------------------ |
-| `hotfix.code-annotations` | boolean/map  | `true`  | Enable the code-annotations hot-fix for Typst output.                                      |
-| `hotfix.skylighting`      | boolean/map  | `true`  | Enable the Skylighting hot-fix for Typst output (overrides block styling and inline code). |
-| `hotfix.typst-title`      | boolean/map  | `true`  | Enable the Typst title hot-fix (evaluates theorem title strings as markup).                |
-
-### Styles
-
-- **`"macos"`** (default): Traffic light buttons (red, yellow, green) on the left, filename on the right.
-- **`"windows"`**: Minimise, maximise, and close buttons on the right, filename on the left.
-- **`"default"`**: Plain filename on the left, no window decorations.
-
-### Block-Level Attributes
-
-Override the style or toggle features for a single code block:
-
-| Attribute                      | Type           | Default | Description                                                                                                          |
-| ------------------------------ | -------------- | ------- | -------------------------------------------------------------------------------------------------------------------- |
-| `code-window-style`            | string         |         | Override the global style for this block: `"macos"`, `"windows"`, or `"default"`.                                    |
-| `code-window-enabled`          | boolean        | `true`  | Set to `false` to disable window chrome while keeping annotations.                                                   |
-| `code-window-no-auto-filename` | boolean        | `false` | Suppress the auto-generated filename for this block.                                                                 |
-| `code-window-collapse`         | boolean/string |         | Render this code block inside a `<details>` element (HTML). Accepts `true` (closed), `false`, `"open"`, `"closed"`.  |
-| `code-window-lines`            | string         |         | Highlighted-lines spec rendered as a chip alongside the filename (e.g. `"1,3-5"`). Falls back to `code-line-numbers`. |
-
-````markdown
-```{.python filename="example.py" code-window-style="windows"}
-print("Windows style for this block only")
-```
-````
-
-### Highlighted Lines Chip
-
-When a code block carries Quarto's `code-line-numbers` attribute with a line specification (e.g. `"1,3-5"`), the spec is rendered as a small chip beside the filename in the title bar.
-
-````markdown
-```{.python filename="loader.py" code-line-numbers="1,4-5"}
-import pandas as pd
-
-def load(path):
-    df = pd.read_csv(path)
-    return df.dropna()
-```
-````
-
-Override the displayed text with `code-window-lines="..."` or disable the chip globally with `lines-label: false`.
-
-### Collapsible Code Windows (HTML)
-
-Set `code-window-collapse` on a block, or `collapse` at the document level, to wrap the code window in a `<details>` element.
-The title bar becomes the `<summary>`.
-
-````markdown
-```{.python filename="long.py" code-window-collapse="closed"}
-# Long block hidden behind a clickable title bar.
-print("Click the title bar to expand.")
-```
-````
-
-This feature applies to HTML and Reveal.js output only.
-
-### Customising Window-Button Icons (HTML)
-
-The macOS and Windows window-button icons are exposed as CSS custom properties so you can override them in your own stylesheet:
-
-```css
-:root {
-  --code-window-macos-icon: url("data:image/svg+xml,...");
-  --code-window-windows-icon: url("data:image/svg+xml,...");
-  --code-window-macos-icon-width: 3.4em;
-  --code-window-windows-icon-width: 3.6em;
-  --code-window-icon-height: 0.85em;
-}
-```
-
-### Temporary Hot-fixes (Typst)
-
-The extension includes three temporary hot-fixes for Typst output that compensate for missing Quarto/Pandoc features.
-All three will be removed once [quarto-dev/quarto-cli#14170](https://github.com/quarto-dev/quarto-cli/pull/14170) is released.
-After that, the extension will focus solely on **auto-filename** and **code-window-style** features.
-
-- **`hotfix.code-annotations`**: processes code annotation markers for Typst, since Quarto does not yet support `code-annotations` in Typst output.
-  The `filename` attribute for code blocks will also become natively supported.
-- **`hotfix.skylighting`**: overrides Pandoc's Skylighting output for Typst to fix block and inline code styling.
-- **`hotfix.typst-title`**: evaluates theorem title strings as Typst markup so that inline formatting (e.g., code) renders correctly.
-
-Each hotfix accepts either a boolean or a map with `enabled` and `quarto-version` keys for per-hotfix version thresholds (upstream fixes may land in different Quarto releases):
-
-```yaml
-extensions:
-  code-window:
-    hotfix:
-      code-annotations: true
-      skylighting:
-        enabled: false
-      typst-title:
-        quarto-version: "1.10.0"
-```
-
-Future removal playbook:
-
-1. Delete `hotfix` parsing from `code-window.lua` (`HOTFIX_DEFAULTS`, hotfix section in `Meta`).
-2. Remove the `hotfix` section from `_schema.yml`.
-3. Remove the skylighting guard and loader in `main.lua`.
-4. Remove annotation processing from `code-window.lua`.
-5. Remove the typst-title fix filter and metadata bridge.
-6. Delete `_modules/hotfix/` directory entirely.
-
-## Example
-
-Here is the source code for a minimal example: [example.qmd](example.qmd).
+[`example.qmd`](example.qmd) is a short, standalone starting point you can copy.
 
-Rendered output:
+## Licence
 
-- [HTML](https://m.canouil.dev/quarto-code-window/).
-- [Typst](https://m.canouil.dev/quarto-code-window/example-typst.pdf).
-- [Reveal.js](https://m.canouil.dev/quarto-code-window/example-revealjs.html).
+[MIT](https://github.com/mcanouil/quarto-code-window?tab=MIT-1-ov-file#readme).

docs/.gitignore

@@ -0,0 +1,13 @@
+/_site/
+/.quarto/
+**/*.quarto_ipynb
+
+# Generated by _scripts/pre-render.sh, removed by _scripts/post-render.sh:
+# changelog.qmd from CHANGELOG.md, _variables.yml from the extension manifest.
+/changelog.qmd
+/_variables.yml
+
+# The extension this repository publishes, copied from the root by
+# _scripts/sync-extension.sh under a `local` owner. Everything else under
+# _extensions/ is a committed dependency. See _extensions/README.md.
+/_extensions/local/

docs/404.qmd

@@ -0,0 +1,17 @@
+---
+title: "Page not found"
+description: "That page does not exist or has moved."
+toc: false
+sidebar: false
+canonical-url: false
+---
+
+::: {.atelier-404}
+
+[404]{.atelier-404-code aria-hidden="true"}
+
+The page you are looking for does not exist or has moved.
+
+[Back to home](/){.atelier-404-home}
+
+:::

docs/_extensions/README.md

@@ -0,0 +1,34 @@
+# Documentation website extensions
+
+The extensions here fall into two groups, told apart by where they sit.
+
+## Committed, under `mcanouil/`
+
+`mcanouil/atelier`, `mcanouil/iconify`, `mcanouil/gitlink`, and `mcanouil/pastel` are dependencies of the website itself: the project type and theme, the footer glyphs, the repository widget, the code block decoration, and the shared palette.
+They arrive with the scaffold, which carries its own copies, and are checked in like any other Quarto extension.
+Beyond that they are managed for you: [Quarto Wizard](https://m.canouil.dev/quarto-wizard) installs them, and the Quarto Extensions Updates workflow keeps them current by scanning this directory.
+
+> [!IMPORTANT]
+> Do not add or update them by hand with the Quarto CLI.
+>
+> `quarto add` and `quarto update` rewrite the manifest and drop the `source` and `source-type` fields, which are the only record of where each extension came from and at which version. An extension without them is invisible to the updater, and stays at whatever version it was left on.
+>
+> `quarto add` also fails here outright: `../_quarto.yml` declares `project: type: atelier`, and it builds a project context before installing anything, so it reports `Unsupported project type atelier` whenever atelier is missing or is the extension being replaced.
+
+## Generated, directly under `_extensions/`
+
+`code-window/` is a copy of the extension this repository publishes, taken from `_extensions/` at the repository root.
+It is ignored by Git and produced by `../_scripts/sync-extension.sh`, so the repository root stays the single source of truth.
+
+Run the sync before previewing the site locally:
+
+```bash
+./docs/_scripts/sync-extension.sh
+quarto render docs
+```
+
+The Pages workflow runs it before every render, so CI always builds the checked-out source.
+
+A real copy is needed, rather than a symlink or a pre-render step.
+Quarto builds its extension registry while reading `_quarto.yml`, before any pre-render script runs, and it does not follow symlinks.
+A shortcode contributed by an extension that is only linked, or only copied in by `pre-render`, is reported as `Shortcode 'code-window' not found` and renders as nothing.

docs/_extensions/mcanouil/atelier/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mickaël Canouil
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.