Skip to content

Commit 4827179

Browse files
AMDphreakAMDphreak
committed
feat: add release CI/CD and project documentation
- Add GitHub Actions release workflow with npm trusted publishing (OIDC) - Create guide module with full project documentation - Update version to 0.1.0 for initial release - Add minimal README.md for npm compatibility - Update demo module as theme showcase
1 parent 2aee995 commit 4827179

18 files changed

Lines changed: 1520 additions & 52 deletions

‎.github/workflows/release.yml‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
name: Release
2+
3+
on:
4+
push:
5+
tags:
6+
- "v*"
7+
8+
permissions:
9+
contents: write
10+
id-token: write # Required for npm trusted publishing (OIDC)
11+
12+
jobs:
13+
release:
14+
runs-on: ubuntu-latest
15+
environment: npm # Must match the environment configured in npm trusted publisher
16+
steps:
17+
- name: Checkout
18+
uses: actions/checkout@v4
19+
with:
20+
fetch-depth: 0
21+
22+
- name: Setup pnpm
23+
uses: pnpm/action-setup@v4
24+
25+
- name: Setup Node.js
26+
uses: actions/setup-node@v4
27+
with:
28+
node-version: "22"
29+
cache: "pnpm"
30+
registry-url: "https://registry.npmjs.org"
31+
32+
- name: Install dependencies
33+
run: pnpm install
34+
35+
- name: Verify package version matches tag
36+
run: |
37+
PACKAGE_VERSION=$(node -p "require('./package.json').version")
38+
TAG_VERSION=${GITHUB_REF#refs/tags/v}
39+
if [ "$PACKAGE_VERSION" != "$TAG_VERSION" ]; then
40+
echo "Error: package.json version ($PACKAGE_VERSION) does not match tag version ($TAG_VERSION)"
41+
exit 1
42+
fi
43+
44+
- name: Create tarball
45+
run: pnpm pack
46+
47+
- name: Generate changelog for release
48+
id: changelog
49+
run: |
50+
# Extract version from tag
51+
VERSION=${GITHUB_REF#refs/tags/v}
52+
53+
# Try to extract changelog section for this version, or use default message
54+
if [ -f "CHANGELOG.adoc" ]; then
55+
# Extract section between this version and next version header
56+
NOTES=$(awk "/^== $VERSION/,/^== [0-9]/" CHANGELOG.adoc | head -n -1 | tail -n +2)
57+
if [ -z "$NOTES" ]; then
58+
NOTES="Release v$VERSION"
59+
fi
60+
else
61+
NOTES="Release v$VERSION"
62+
fi
63+
64+
# Write to file to handle multiline
65+
echo "$NOTES" > release_notes.md
66+
67+
- name: Create GitHub Release
68+
uses: softprops/action-gh-release@v2
69+
with:
70+
body_path: release_notes.md
71+
files: |
72+
antora-dark-theme-*.tgz
73+
generate_release_notes: true
74+
env:
75+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
76+
77+
- name: Publish to npm (trusted publishing)
78+
if: ${{ !contains(github.ref, '-') }}
79+
run: npm publish --access public --provenance

‎CHANGELOG.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ All notable changes to this project will be documented in this file.
55
The format is based on https://keepachangelog.com/en/1.1.0/[Keep a Changelog],
66
and this project adheres to https://semver.org/spec/v2.0.0.html[Semantic Versioning].
77

8-
== [1.0.0] - 2026-01-26
8+
== [0.1.0] - 2026-01-29
99

1010
=== Added
1111

‎README.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Antora Dark Theme
2+
3+
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
4+
[![Antora 3.x](https://img.shields.io/badge/antora-3.x-purple.svg)](https://antora.org)
5+
6+
Dark mode supplemental UI for [Antora](https://antora.org) documentation sites.
7+
8+
## Install
9+
10+
```bash
11+
pnpm add -D github:the-dev-center/antora-dark-theme
12+
```
13+
14+
Then configure your `antora-playbook.yml`:
15+
16+
```yaml
17+
ui:
18+
bundle:
19+
url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
20+
snapshot: true
21+
supplemental_files: ./node_modules/antora-dark-theme/supplemental-ui
22+
```
23+
24+
## Features
25+
26+
- Dark mode toggle button (sun/moon icons)
27+
- System preference detection
28+
- Persistent preference via localStorage
29+
- No flash of unstyled content (FOUC)
30+
- Works with Antora Default UI — no fork required
31+
32+
## Documentation
33+
34+
Full documentation and live demo: **https://the-dev-center.github.io/antora-dark-theme**
35+
36+
## License
37+
38+
[MIT](LICENSE)

‎antora-playbook.yml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
1-
# Antora Playbook for building the Dark Theme Demo site
1+
# Antora Playbook for building the documentation site
22
# This playbook is used for local development and CI builds
33

44
site:
5-
title: Antora Dark Theme Demo
5+
title: Antora Dark Theme
66
url: https://the-dev-center.github.io/antora-dark-theme
7-
start_page: theme-demo::index.adoc
7+
start_page: antora-dark-theme:guide:index.adoc
88

99
content:
1010
sources:

‎docs/antora.yml‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
1-
name: theme-demo
2-
title: Dark Theme Demo
3-
version: '1.0'
4-
start_page: ROOT:index.adoc
1+
name: antora-dark-theme
2+
title: Antora Dark Theme
3+
version: "0.1"
4+
start_page: guide:index.adoc
55
nav:
6+
- modules/guide/nav.adoc
67
- modules/ROOT/nav.adoc

‎docs/modules/ROOT/nav.adoc‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
1-
* xref:index.adoc[Home]
1+
.Theme Demo
2+
* xref:index.adoc[Demo Home]
23
* xref:typography.adoc[Typography]
34
* xref:code-blocks.adoc[Code Blocks]
45
* xref:admonitions.adoc[Admonitions]

‎docs/modules/ROOT/pages/index.adoc‎

Lines changed: 10 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,17 @@
1-
= Antora Dark Theme Demo
2-
:navtitle: Home
1+
= Theme Demo
2+
:navtitle: Demo Home
33
:description: A comprehensive demonstration of the Antora Dark Theme styling.
44

5-
Welcome to the *Antora Dark Theme* demonstration site.
6-
This documentation showcases all the UI elements styled by the dark theme.
5+
This section showcases all the UI elements styled by the dark theme.
6+
Use these pages to see how different AsciiDoc elements render in both light and dark modes.
77

8-
== Getting Started
8+
TIP: Use the *theme toggle button* in the navbar (sun/moon icon) to switch between light and dark modes.
99

10-
Use the *theme toggle button* in the navbar (sun/moon icon) to switch between light and dark modes.
11-
12-
The theme supports:
13-
14-
* Automatic detection of your system's color scheme preference
15-
* Manual toggle via the navbar button
16-
* Persistent preference saved in your browser
17-
18-
== Features Overview
10+
== Demo Pages
1911

2012
[cols="1,2"]
2113
|===
22-
| Feature | Description
14+
| Page | Description
2315

2416
| xref:typography.adoc[Typography]
2517
| Headings, paragraphs, inline formatting, and links
@@ -43,36 +35,14 @@ The theme supports:
4335
| Image blocks and figure captions
4436
|===
4537

46-
== Quick Example
47-
48-
Here's a quick code example:
38+
== Quick Code Example
4939

5040
[source,javascript]
5141
----
52-
// Toggle dark mode
42+
// Toggle dark mode programmatically
5343
function toggleTheme() {
5444
document.documentElement.classList.toggle('dark-theme');
5545
}
5646
----
5747

58-
TIP: Click the toggle button in the navbar to see the theme change in action!
59-
60-
== Installation
61-
62-
Install via npm or pnpm:
63-
64-
[source,bash]
65-
----
66-
pnpm add -D antora-dark-theme
67-
----
68-
69-
Then configure your `antora-playbook.yml`:
70-
71-
[source,yaml]
72-
----
73-
ui:
74-
bundle:
75-
url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
76-
snapshot: true
77-
supplemental_files: ./node_modules/antora-dark-theme/supplemental-ui
78-
----
48+
NOTE: For installation and usage instructions, see xref:guide:index.adoc[Getting Started].

‎docs/modules/guide/nav.adoc‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
.Documentation
2+
* xref:index.adoc[Getting Started]
3+
* xref:installation.adoc[Installation]
4+
* xref:configuration.adoc[Configuration]
5+
* xref:customization.adoc[Customization]
6+
* xref:how-it-works.adoc[How It Works]
7+
* xref:troubleshooting.adoc[Troubleshooting]

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

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
= Configuration
2+
:navtitle: Configuration
3+
:description: Configuration options for the Antora Dark Theme.
4+
5+
The dark theme works out of the box with sensible defaults.
6+
This page covers the configuration options available.
7+
8+
== Playbook Configuration
9+
10+
The only required configuration is adding the supplemental files to your `antora-playbook.yml`:
11+
12+
[source,yaml]
13+
----
14+
ui:
15+
bundle:
16+
url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
17+
snapshot: true
18+
supplemental_files: ./node_modules/antora-dark-theme/supplemental-ui
19+
----
20+
21+
== Default Behavior
22+
23+
=== Theme Detection
24+
25+
The theme automatically detects your preference in this order:
26+
27+
. *Saved preference* - If you've previously toggled the theme, that choice is remembered
28+
. *System preference* - If no saved preference exists, the theme checks your OS dark mode setting
29+
. *Light mode* - Falls back to light mode if neither of the above applies
30+
31+
=== Storage Key
32+
33+
The theme stores your preference in `localStorage` under the key `antora-theme`.
34+
Values are either `light` or `dark`.
35+
36+
To programmatically set the theme:
37+
38+
[source,javascript]
39+
----
40+
// Set dark mode
41+
localStorage.setItem('antora-theme', 'dark');
42+
location.reload();
43+
44+
// Set light mode
45+
localStorage.setItem('antora-theme', 'light');
46+
location.reload();
47+
48+
// Clear preference (use system default)
49+
localStorage.removeItem('antora-theme');
50+
location.reload();
51+
----
52+
53+
== File Structure
54+
55+
The supplemental UI consists of four files:
56+
57+
[source]
58+
----
59+
supplemental-ui/
60+
├── css/
61+
│ └── site-extra.css # Dark mode CSS styles
62+
├── js/
63+
│ └── site-dark-mode.js # Toggle button logic
64+
└── partials/
65+
├── footer-scripts.hbs # Loads the dark mode script
66+
└── head-meta.hbs # Loads CSS and prevents FOUC
67+
----
68+
69+
Each file serves a specific purpose:
70+
71+
`site-extra.css`::
72+
Contains all dark mode styles using the `html.dark-theme` selector prefix.
73+
74+
`site-dark-mode.js`::
75+
Injects the toggle button and handles theme switching logic.
76+
77+
`head-meta.hbs`::
78+
Handlebars partial injected into `<head>` that loads CSS and prevents flash of unstyled content.
79+
80+
`footer-scripts.hbs`::
81+
Handlebars partial that loads the JavaScript at the end of the page body.

0 commit comments

Comments
 (0)