Skip to content

Commit c439867

Browse files
AMDphreakAMDphreak
committed
docs: replace invalid stacked supplemental_files example with Antora-correct patterns
Antora accepts one directory path or virtual file entries; a YAML list of multiple directories was never valid. Document merged directory, bundle + virtual files, and virtual partial overrides; update installation guide and changelog.
1 parent d47732c commit c439867

4 files changed

Lines changed: 83 additions & 16 deletions

File tree

‎CHANGELOG.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ Entries below are in **chronological order** by date: prior release, then the **
1010

1111
== Unreleased
1212

13+
* Documentation: replace the invalid “stacked directories” `supplemental_files` example with Antora-correct options (single merged directory, pre-built bundle + virtual files, or virtual partial overrides). See https://docs.antora.org/antora/latest/playbook/ui-supplemental-files[Antora supplemental UI].
1314
* `package.json` `packageManager`: bump pnpm to **10.33.0** (matches `pnpm/action-setup` in CI, including link:https://github.com/antora-supplemental/antora-build-action[antora-build-action], so the action and Corepack no longer disagree).
1415
* GitHub Pages deploy workflow: use link:https://github.com/antora-supplemental/antora-build-action[antora-build-action] **v2** with `setup_pnpm: false`, `setup_node: false`, and `install_dependencies: false` after the job’s own `pnpm` / `setup-node` steps (no duplicate toolchain setup).
1516

‎README.adoc‎

Lines changed: 37 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ Your support helps the Antora team prioritize this feature!
4242

4343
=== Which installation path should I use?
4444

45-
* **If your project already uses Node/npm/pnpm** (common for Antora sites) — Prefer *Method 1* (install from npm) and *Method 2* when you need layered overrides. The theme stays in `package.json` / your lockfile like the rest of your toolchain.
45+
* **If your project already uses Node/npm/pnpm** (common for Antora sites) — Prefer *Method 1* (install from npm). To add your own supplemental files on top of this theme, follow *Method 2* (valid Antora patterns only).
4646
* **If you want no JavaScript install step** (minimal CI image, or a repo without Node) — Use *Method 3* (pre-built `ui-bundle.zip`): one URL in the playbook, no `node_modules`.
4747

4848
=== Method 1: Use as npm dependency (recommended for Node-based projects)
@@ -91,9 +91,41 @@ ui:
9191
supplemental_files: ./node_modules/antora-dark-theme/supplemental-ui
9292
----
9393

94-
=== Method 2: Stacked supplemental_files (project overrides)
94+
=== Method 2: Project overrides (valid Antora options)
9595

96-
To override or extend this theme with your own supplemental UI, use an array for `supplemental_files`. Paths listed **later** take precedence.
96+
Antora’s `ui.supplemental_files` accepts *either* a single filesystem directory *or* an array of https://docs.antora.org/antora/latest/playbook/ui-supplemental-files[virtual files] (`path` + `contents`).
97+
A YAML list of multiple **directories** is not supported—the array form is only for virtual entries.
98+
99+
*Merged directory (recommended when you use npm and need custom partials/CSS):* Copy `node_modules/antora-dark-theme/supplemental-ui` into your repo (for example `supplemental-ui/`), merge your changes on top, then point the playbook at that *one* folder:
100+
101+
[source,yaml]
102+
----
103+
ui:
104+
bundle:
105+
url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
106+
snapshot: true
107+
supplemental_files: ./supplemental-ui
108+
----
109+
110+
*Pre-built theme bundle + virtual files:* Use the release `ui-bundle.zip` (default UI + dark theme already combined) and add only extra assets with a virtual `supplemental_files` array:
111+
112+
[source,yaml]
113+
----
114+
ui:
115+
bundle:
116+
url: https://github.com/antora-supplemental/antora-dark-theme/releases/latest/download/ui-bundle.zip
117+
snapshot: true
118+
supplemental_files:
119+
- path: ui.yml
120+
contents: |
121+
static_files:
122+
- favicon.ico
123+
- path: favicon.ico
124+
contents: ./branding/favicon.ico
125+
----
126+
127+
*Virtual override of a single UI file:* Each entry must use `path` and `contents` (inline or path to a file on disk).
128+
If you replace a partial such as `partials/head-meta.hbs`, your file must still load this theme’s CSS and scripts (start from the theme’s partial), or use a merged directory instead.
97129

98130
[source,yaml]
99131
----
@@ -102,8 +134,8 @@ ui:
102134
url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
103135
snapshot: true
104136
supplemental_files:
105-
- ./node_modules/antora-dark-theme/supplemental-ui
106-
- ./site/src
137+
- path: partials/head-meta.hbs
138+
contents: ./my-supplemental-ui/partials/head-meta.hbs
107139
----
108140

109141
=== Method 3: Pre-built UI bundle (no JavaScript toolchain)

‎README.md‎

Lines changed: 34 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ Dark mode supplemental UI for [Antora](https://antora.org) documentation sites.
99

1010
### Which installation path should I use?
1111

12-
- **If your project already uses Node/npm/pnpm** (common for Antora sites) — use **Method 1** (npm) and **Method 2** when you need layered overrides. The theme stays in `package.json` / your lockfile like the rest of your toolchain.
12+
- **If your project already uses Node/npm/pnpm** (common for Antora sites) — use **Method 1** (npm). To add your own supplemental files on top of this theme, use **Method 2** (valid Antora patterns only—see below).
1313
- **If you want no JavaScript install step** (minimal CI, or a repo without Node) — use **Method 3** (pre-built `ui-bundle.zip`): one URL in the playbook, no `node_modules`.
1414

1515
### Method 1: npm dependency (recommended for Node-based projects)
@@ -38,18 +38,46 @@ ui:
3838
supplemental_files: ./node_modules/antora-dark-theme/supplemental-ui
3939
```
4040
41-
### Method 2: Stacked `supplemental_files` (project overrides)
41+
### Method 2: Project overrides (valid Antora options)
4242
43-
Paths listed **later** take precedence.
43+
Antora’s `ui.supplemental_files` accepts **either** a single directory path **or** an array of [virtual files](https://docs.antora.org/antora/latest/playbook/ui-supplemental-files) (`path` + `contents`). A YAML list of multiple **directories** is not supported—the array form is only for virtual entries.
44+
45+
**Merged directory (recommended when you use npm and need custom partials/CSS):** Copy `node_modules/antora-dark-theme/supplemental-ui` into your repo (for example `supplemental-ui/`), merge your changes on top, then point the playbook at that **one** folder:
46+
47+
```yaml
48+
ui:
49+
bundle:
50+
url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
51+
snapshot: true
52+
supplemental_files: ./supplemental-ui
53+
```
54+
55+
**Pre-built theme bundle + virtual files:** Use the release `ui-bundle.zip` (default UI + dark theme already combined) and add only extra assets with a virtual `supplemental_files` array:
56+
57+
```yaml
58+
ui:
59+
bundle:
60+
url: https://github.com/antora-supplemental/antora-dark-theme/releases/latest/download/ui-bundle.zip
61+
snapshot: true
62+
supplemental_files:
63+
- path: ui.yml
64+
contents: |
65+
static_files:
66+
- favicon.ico
67+
- path: favicon.ico
68+
contents: ./branding/favicon.ico
69+
```
70+
71+
**Virtual override of a single UI file:** Each entry must use `path` and `contents` (inline or path to a file). If you replace a partial such as `partials/head-meta.hbs`, your file must still load this theme’s CSS and scripts (start from the theme’s partial), or use a merged directory instead.
4472

4573
```yaml
4674
ui:
4775
bundle:
4876
url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
4977
snapshot: true
5078
supplemental_files:
51-
- ./node_modules/antora-dark-theme/supplemental-ui
52-
- ./site/src
79+
- path: partials/head-meta.hbs
80+
contents: ./my-supplemental-ui/partials/head-meta.hbs
5381
```
5482

5583
### Method 3: Pre-built UI bundle (no JavaScript toolchain)
@@ -61,7 +89,7 @@ ui:
6189
snapshot: true
6290
```
6391

64-
### Method 4: Copy `supplemental-ui` into your repo
92+
### Method 4: Copy `supplemental-ui` into your repo (vendor the theme)
6593

6694
Vendor or fork the theme assets by copying the `supplemental-ui` folder into your project, then:
6795

‎docs/modules/guide/pages/installation.adoc‎

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ There are several ways to add the dark theme to your Antora project.
66

77
== Which installation path should I use?
88

9-
* **If your project already uses Node/npm/pnpm** (common for Antora sites) — Prefer *Method 1* (npm registry) or *Method 2* (GitHub as a package dependency). Both keep the theme in your package graph and lockfile.
9+
* **If your project already uses Node/npm/pnpm** (common for Antora sites) — Prefer *Method 1* (npm registry) or *Method 2* (GitHub as a package dependency). Both keep the theme in your package graph and lockfile. For custom supplemental UI on top of this theme, merge into a single directory or use virtual files (see <<override-theme>>).
1010
* **If you want no JavaScript install step** (minimal CI, or a repo without Node) — Use *Method 3* (pre-built `ui-bundle.zip`).
1111

1212
== Method 1: npm registry (recommended)
@@ -55,19 +55,25 @@ ui:
5555
supplemental_files: ./node_modules/antora-dark-theme/supplemental-ui
5656
----
5757

58-
To layer your own supplemental UI after this theme, use an array; later paths win:
58+
[[override-theme]]
59+
=== Adding your own supplemental UI on top of this theme
60+
61+
Antora’s `ui.supplemental_files` accepts *either* a single filesystem directory *or* an array of https://docs.antora.org/antora/latest/playbook/ui-supplemental-files[virtual files] (`path` + `contents`).
62+
You cannot list multiple directories in the YAML array.
63+
64+
*Merged directory (recommended):* Copy `node_modules/antora-dark-theme/supplemental-ui` into your project (for example `supplemental-ui/`), merge your `partials/`, `css/`, and other assets, then set `supplemental_files` to that *one* path:
5965

6066
[source,yaml]
6167
----
6268
ui:
6369
bundle:
6470
url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
6571
snapshot: true
66-
supplemental_files:
67-
- ./node_modules/antora-dark-theme/supplemental-ui
68-
- ./site/src
72+
supplemental_files: ./supplemental-ui
6973
----
7074

75+
*Pre-built theme bundle + virtual files:* If you use the release `ui-bundle.zip`, the theme is already in the bundle; add only virtual `supplemental_files` entries for extra assets (see the Antora docs linked above).
76+
7177
== Method 2: Install from GitHub as a package dependency
7278

7379
Useful for an unreleased commit or when you prefer the `github:` protocol:

0 commit comments

Comments
 (0)