docs: prioritize npm workflow; add if/then to Quick Start

Reorder README (AsciiDoc + Markdown) so Method 1 is the npm-based
install; pre-built ui-bundle is for no-Node setups. Align the Antora
installation guide with the same ordering and stacked supplementalexample.

Author: AMDphreak

README.adoc

@@ -40,45 +40,14 @@ Your support helps the Antora team prioritize this feature!
 
 == Quick Start
 
-=== Method 1: Use pre-built bundle (Recommended)
+=== Which installation path should I use?
 
-The easiest way to use this theme is to point your Antora playbook directly to the latest pre-built UI bundle. This includes the Antora Default UI plus all dark mode enhancements.
+* **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.
+* **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`.
 
-. Configure your `antora-playbook.yml` to use the release bundle:
-+
-[source,yaml]
-----
-ui:
-  bundle:
-    url: https://github.com/antora-supplemental/antora-dark-theme/releases/latest/download/ui-bundle.zip
-    snapshot: true
-----
-
-=== Method 2: Copy supplemental-ui folder
-
-If you want to customize the dark mode styles or logic locally, you can copy the `supplemental-ui` folder into your project.
-
-. Copy the `supplemental-ui` folder to your project root:
-+
-[source,bash]
-----
-cp -r supplemental-ui /path/to/your/antora-project/
-----
-
-. Configure your `antora-playbook.yml` to use the supplemental files alongside the default UI:
-+
-[source,yaml]
-----
-ui:
-  bundle:
-    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
-    snapshot: true
-  supplemental_files: ./supplemental-ui
-----
-
-=== Method 3: Use as npm dependency
+=== Method 1: Use as npm dependency (recommended for Node-based projects)
 
-You can also install this theme as a dev dependency. This is useful for version tracking and easy updates within your project's ecosystem.
+Install this theme as a dev dependency so the version is tracked with your project.
 
 [tabs]
 ====
@@ -122,9 +91,9 @@ ui:
   supplemental_files: ./node_modules/antora-dark-theme/supplemental-ui
 ----
 
-=== Method 4: Stacked Overrides (Deep Customization)
+=== Method 2: Stacked supplemental_files (project overrides)
 
-To override the dark theme's own overrides with your project-specific customizations, use an array for `supplemental_files`. Paths listed later take precedence.
+To override or extend this theme with your own supplemental UI, use an array for `supplemental_files`. Paths listed **later** take precedence.
 
 [source,yaml]
 ----
@@ -137,6 +106,42 @@ ui:
     - ./site/src
 ----
 
+=== Method 3: Pre-built UI bundle (no JavaScript toolchain)
+
+Point your Antora playbook at the latest release bundle. This ships the Antora Default UI plus all dark mode enhancements—no npm install.
+
+. Configure your `antora-playbook.yml`:
++
+[source,yaml]
+----
+ui:
+  bundle:
+    url: https://github.com/antora-supplemental/antora-dark-theme/releases/latest/download/ui-bundle.zip
+    snapshot: true
+----
+
+=== Method 4: Copy `supplemental-ui` into your repo
+
+If you want to **vendor** or heavily customize the dark mode assets, copy the `supplemental-ui` folder into your project (instead of resolving it from npm).
+
+. Copy the folder:
++
+[source,bash]
+----
+cp -r supplemental-ui /path/to/your/antora-project/
+----
+
+. Point the playbook at your copy, on top of the default UI bundle:
++
+[source,yaml]
+----
+ui:
+  bundle:
+    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
+    snapshot: true
+  supplemental_files: ./supplemental-ui
+----
+
 == Live Demo
 
 See the dark theme in action: {url-demo}[Live Demo]

README.md

@@ -5,9 +5,14 @@
 
 Dark mode supplemental UI for [Antora](https://antora.org) documentation sites.
 
-## Install
+## Quick start
 
-Install the published package as a development dependency:
+### Which installation path should I use?
+
+- **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.
+- **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`.
+
+### Method 1: npm dependency (recommended for Node-based projects)
 
 ```bash
 # npm
@@ -23,49 +28,49 @@ yarn add -D antora-dark-theme
 bun add -d antora-dark-theme
 ```
 
-Then configure your playbook file(s) (typically `antora-playbook.yml`) to use the theme.
-
-### Method 1: Use pre-built bundle (Recommended)
-
-The easiest way to use this theme is to point your Antora playbook directly to the latest pre-built UI bundle. This includes the Antora Default UI plus all dark mode enhancements without requiring any local package installation.
+Then reference the supplemental UI from `node_modules` in `antora-playbook.yml` (or your playbook file):
 
 ```yaml
 ui:
   bundle:
-    url: https://github.com/antora-supplemental/antora-dark-theme/releases/latest/download/ui-bundle.zip
+    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
     snapshot: true
+  supplemental_files: ./node_modules/antora-dark-theme/supplemental-ui
 ```
 
-### Method 2: Use as npm dependency
+### Method 2: Stacked `supplemental_files` (project overrides)
 
-Install the package:
+Paths listed **later** take precedence.
 
-```bash
-pnpm add -D antora-dark-theme
+```yaml
+ui:
+  bundle:
+    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
+    snapshot: true
+  supplemental_files:
+    - ./node_modules/antora-dark-theme/supplemental-ui
+    - ./site/src
 ```
 
-Then reference the supplemental UI from `node_modules`:
+### Method 3: Pre-built UI bundle (no JavaScript toolchain)
 
 ```yaml
 ui:
   bundle:
-    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
+    url: https://github.com/antora-supplemental/antora-dark-theme/releases/latest/download/ui-bundle.zip
     snapshot: true
-  supplemental_files: ./node_modules/antora-dark-theme/supplemental-ui
 ```
 
-### Method 3: Stacked Overrides (Deep Customization)
+### Method 4: Copy `supplemental-ui` into your repo
 
-To override the dark theme's own overrides with your project-specific customizations, use an array for `supplemental_files`. Paths listed later take precedence.
+Vendor or fork the theme assets by copying the `supplemental-ui` folder into your project, then:
 
 ```yaml
 ui:
   bundle:
     url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
     snapshot: true
-  supplemental_files:
-    - ./node_modules/antora-dark-theme/supplemental-ui
-    - ./site/src
+  supplemental_files: ./supplemental-ui
 ```
 
 ## Features
@@ -80,7 +85,7 @@ ui:
 
 Full documentation and live demo: [antora-supplemental.github.io/antora-dark-theme](https://antora-supplemental.github.io/antora-dark-theme)
 
-For other installation options, including the pre-built UI bundle and copying `supplemental-ui` directly, see the [official README.adoc](https://github.com/antora-supplemental/antora-dark-theme/README.adoc).
+For the full AsciiDoc guide (same content, more detail), see [README.adoc](https://github.com/antora-supplemental/antora-dark-theme/blob/main/README.adoc).
 
 ## License
 

docs/modules/guide/pages/installation.adoc

@@ -4,39 +4,47 @@
 
 There are several ways to add the dark theme to your Antora project.
 
-== Method 1: Install from GitHub (Recommended)
+== Which installation path should I use?
 
-Install directly from the GitHub repository:
+* **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.
+* **If you want no JavaScript install step** (minimal CI, or a repo without Node) — Use *Method 3* (pre-built `ui-bundle.zip`).
+
+== Method 1: npm registry (recommended)
+
+Install the published package:
 
 [tabs]
 ====
 pnpm::
 +
 [source,bash]
 ----
-# Latest version
-pnpm add -D github:antora-supplemental/antora-dark-theme
-
-# Specific version
-pnpm add -D github:antora-supplemental/antora-dark-theme#v0.1.0
+pnpm add -D antora-dark-theme
 ----
 
 npm::
 +
 [source,bash]
 ----
-npm install --save-dev github:antora-supplemental/antora-dark-theme
+npm install --save-dev antora-dark-theme
 ----
 
 yarn::
 +
 [source,bash]
 ----
-yarn add -D github:antora-supplemental/antora-dark-theme
+yarn add -D antora-dark-theme
+----
+
+bun::
++
+[source,bash]
+----
+bun add -D antora-dark-theme
 ----
 ====
 
-Then configure your `antora-playbook.yml`:
+Then configure your `antora-playbook.yml` with the Antora Default UI bundle and this theme’s supplemental files:
 
 [source,yaml]
 ----
@@ -47,39 +55,68 @@ ui:
   supplemental_files: ./node_modules/antora-dark-theme/supplemental-ui
 ----
 
-== Method 2: Install from npm Registry
+To layer your own supplemental UI after this theme, use an array; later paths win:
+
+[source,yaml]
+----
+ui:
+  bundle:
+    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
+    snapshot: true
+  supplemental_files:
+    - ./node_modules/antora-dark-theme/supplemental-ui
+    - ./site/src
+----
 
-If the package is published to npm:
+== Method 2: Install from GitHub as a package dependency
+
+Useful for an unreleased commit or when you prefer the `github:` protocol:
 
 [tabs]
 ====
 pnpm::
 +
 [source,bash]
 ----
-pnpm add -D antora-dark-theme
+# Latest default branch
+pnpm add -D github:antora-supplemental/antora-dark-theme
+
+# Specific tag
+pnpm add -D github:antora-supplemental/antora-dark-theme#v0.1.0
 ----
 
 npm::
 +
 [source,bash]
 ----
-npm install --save-dev antora-dark-theme
+npm install --save-dev github:antora-supplemental/antora-dark-theme
 ----
 
 yarn::
 +
 [source,bash]
 ----
-yarn add -D antora-dark-theme
+yarn add -D github:antora-supplemental/antora-dark-theme
 ----
 ====
 
-Same playbook configuration as Method 1.
+Use the same `supplemental_files` path as *Method 1* (`./node_modules/antora-dark-theme/supplemental-ui`).
+
+== Method 3: Pre-built UI bundle (no JavaScript toolchain)
+
+Point your playbook at the release artifact (Antora Default UI + dark theme, no `npm install`):
 
-== Method 3: Install from Release Tarball
+[source,yaml]
+----
+ui:
+  bundle:
+    url: https://github.com/antora-supplemental/antora-dark-theme/releases/latest/download/ui-bundle.zip
+    snapshot: true
+----
 
-Download a specific release directly:
+== Method 4: Install from release tarball
+
+Download a specific `.tgz` from link:https://github.com/antora-supplemental/antora-dark-theme/releases[GitHub Releases] if you need an exact version without using the npm registry:
 
 [tabs]
 ====
@@ -105,9 +142,11 @@ yarn add -D https://github.com/antora-supplemental/antora-dark-theme/releases/do
 ----
 ====
 
-== Method 4: Copy supplemental-ui Folder
+Then use the same playbook `supplemental_files` path as *Method 1*.
+
+== Method 5: Copy `supplemental-ui` folder
 
-For maximum control, copy the `supplemental-ui` folder directly into your project:
+For maximum control, copy the `supplemental-ui` folder into your project:
 
 . Clone or download the repository
 . Copy the `supplemental-ui` folder to your project root:
@@ -128,7 +167,7 @@ ui:
   supplemental_files: ./supplemental-ui
 ----
 
-== Verify Installation
+== Verify installation
 
 Build your site to verify the installation:
 
@@ -140,6 +179,3 @@ antora antora-playbook.yml
 Open the generated site in a browser.
 You should see a sun/moon toggle button in the navbar.
 Click it to switch between light and dark modes.
-
-
-