Skip to content

Commit 66a5474

Browse files
AMDphreakAMDphreak
committed
Add demo docs, GitHub Pages deploy, and fix TOC menu h3 dark text color
1 parent 817631f commit 66a5474

19 files changed

Lines changed: 3223 additions & 24 deletions

‎.github/workflows/deploy.yml‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
name: Deploy to GitHub Pages
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
pull_request:
8+
branches:
9+
- main
10+
workflow_dispatch:
11+
12+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
13+
permissions:
14+
contents: read
15+
pages: write
16+
id-token: write
17+
18+
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
19+
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
20+
concurrency:
21+
group: "pages"
22+
cancel-in-progress: false
23+
24+
jobs:
25+
build:
26+
runs-on: ubuntu-latest
27+
steps:
28+
- name: Checkout
29+
uses: actions/checkout@v4
30+
with:
31+
fetch-depth: 0
32+
33+
- name: Setup pnpm
34+
uses: pnpm/action-setup@v4
35+
with:
36+
version: 10
37+
38+
- name: Setup Node.js
39+
uses: actions/setup-node@v4
40+
with:
41+
node-version: '20'
42+
cache: 'pnpm'
43+
44+
- name: Install dependencies
45+
run: pnpm install
46+
47+
- name: Build Antora site
48+
run: pnpm build
49+
50+
- name: Setup Pages
51+
uses: actions/configure-pages@v5
52+
53+
- name: Upload artifact
54+
uses: actions/upload-pages-artifact@v3
55+
with:
56+
path: './build/site'
57+
58+
deploy:
59+
if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
60+
environment:
61+
name: github-pages
62+
url: ${{ steps.deployment.outputs.page_url }}
63+
runs-on: ubuntu-latest
64+
needs: build
65+
steps:
66+
- name: Deploy to GitHub Pages
67+
id: deployment
68+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
# Build output
22
build/
33
public/
4+
.cache/
45

56
# Dependencies
67
node_modules/

‎README.adoc‎

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,14 @@
66
:source-highlighter: highlight.js
77
:url-antora: https://antora.org
88
:url-antora-ui: https://gitlab.com/antora/antora-ui-default
9+
:url-demo: https://the-dev-center.github.io/antora-dark-theme
910

1011
A dark mode supplemental UI theme for {url-antora}[Antora] documentation sites.
1112
This theme layers on top of the {url-antora-ui}[Antora Default UI] without requiring modifications to the base UI bundle.
1213

1314
image::https://img.shields.io/badge/license-MIT-blue.svg[License: MIT]
1415
image::https://img.shields.io/badge/antora-3.x-purple.svg[Antora 3.x]
16+
image::https://github.com/the-dev-center/antora-dark-theme/actions/workflows/deploy.yml/badge.svg[Build Status,link=https://github.com/the-dev-center/antora-dark-theme/actions/workflows/deploy.yml]
1517

1618
toc::[]
1719

@@ -77,6 +79,10 @@ ui:
7779
supplemental_files: ./node_modules/antora-dark-theme/supplemental-ui
7880
----
7981

82+
== Live Demo
83+
84+
See the dark theme in action: {url-demo}[Live Demo]
85+
8086
== File Structure
8187

8288
[source]
@@ -90,9 +96,17 @@ antora-dark-theme/
9096
│ └── partials/
9197
│ ├── footer-scripts.hbs # Loads the dark mode script
9298
│ └── head-meta.hbs # Loads CSS and prevents FOUC
99+
├── docs/ # Demo documentation
100+
│ ├── antora.yml # Component descriptor
101+
│ └── modules/ROOT/
102+
│ ├── nav.adoc # Navigation
103+
│ └── pages/ # Sample pages
93104
├── examples/
94-
│ ├── antora-playbook.yml # Example playbook configuration
95-
│ └── antora-playbook-local.yml
105+
│ ├── antora-playbook.yml # Example playbook (npm install)
106+
│ └── antora-playbook-local.yml # Example playbook (direct copy)
107+
├── .github/workflows/
108+
│ └── deploy.yml # GitHub Pages deployment
109+
├── antora-playbook.yml # Playbook for building demo site
96110
├── package.json
97111
├── LICENSE
98112
└── README.adoc

‎antora-playbook.yml‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Antora Playbook for building the Dark Theme Demo site
2+
# This playbook is used for local development and CI builds
3+
4+
site:
5+
title: Antora Dark Theme Demo
6+
url: https://the-dev-center.github.io/antora-dark-theme
7+
start_page: theme-demo::index.adoc
8+
9+
content:
10+
sources:
11+
- url: .
12+
branches: HEAD
13+
start_path: docs
14+
15+
ui:
16+
bundle:
17+
url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
18+
snapshot: true
19+
supplemental_files: ./supplemental-ui
20+
21+
output:
22+
dir: ./build/site
23+
24+
asciidoc:
25+
attributes:
26+
source-highlighter: highlight.js
27+
icons: font

‎docs/antora.yml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
name: theme-demo
2+
title: Dark Theme Demo
3+
version: '1.0'
4+
start_page: ROOT:index.adoc
5+
nav:
6+
- modules/ROOT/nav.adoc

‎docs/modules/ROOT/nav.adoc‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
* xref:index.adoc[Home]
2+
* xref:typography.adoc[Typography]
3+
* xref:code-blocks.adoc[Code Blocks]
4+
* xref:admonitions.adoc[Admonitions]
5+
* xref:tables.adoc[Tables]
6+
* xref:blocks.adoc[Blocks & Quotes]
7+
* xref:lists.adoc[Lists]
8+
* xref:images.adoc[Images & Media]

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

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
= Admonitions
2+
:navtitle: Admonitions
3+
:description: Demonstrates note, tip, warning, caution, and important blocks.
4+
5+
Admonitions draw attention to important information.
6+
The dark theme styles each type distinctively.
7+
8+
== Note
9+
10+
NOTE: This is a note admonition.
11+
Use notes for additional information that supplements the main content.
12+
13+
== Tip
14+
15+
TIP: This is a tip admonition.
16+
Tips provide helpful suggestions or best practices.
17+
18+
== Important
19+
20+
IMPORTANT: This is an important admonition.
21+
Use this for critical information the reader must not miss.
22+
23+
== Warning
24+
25+
WARNING: This is a warning admonition.
26+
Warnings alert readers to potential problems or risks.
27+
28+
== Caution
29+
30+
CAUTION: This is a caution admonition.
31+
Cautions indicate actions that could have negative consequences.
32+
33+
== Admonitions with Titles
34+
35+
[NOTE]
36+
.Configuration Required
37+
====
38+
You must configure the `antora-playbook.yml` file before building the site.
39+
See the xref:index.adoc[installation guide] for details.
40+
====
41+
42+
[TIP]
43+
.Performance Optimization
44+
====
45+
Enable caching in your playbook for faster subsequent builds:
46+
47+
[source,yaml]
48+
----
49+
runtime:
50+
cache_dir: .cache/antora
51+
----
52+
====
53+
54+
[WARNING]
55+
.Breaking Changes in v2.0
56+
====
57+
The configuration format changed in version 2.0.
58+
Please review the migration guide before upgrading.
59+
====
60+
61+
== Admonitions with Complex Content
62+
63+
[IMPORTANT]
64+
.Multi-step Process
65+
====
66+
Follow these steps in order:
67+
68+
. Clone the repository
69+
. Install dependencies with `pnpm install`
70+
. Configure your playbook
71+
. Run `pnpm build`
72+
73+
[source,bash]
74+
----
75+
git clone https://github.com/the-dev-center/antora-dark-theme.git
76+
cd antora-dark-theme
77+
pnpm install
78+
pnpm build
79+
----
80+
====
81+
82+
[CAUTION]
83+
.Data Loss Warning
84+
====
85+
The following actions are *irreversible*:
86+
87+
* Deleting a branch without a backup
88+
* Force pushing to a shared branch
89+
* Running `git clean -fd` without reviewing changes
90+
91+
Always create backups before performing destructive operations.
92+
93+
[cols="1,1"]
94+
|===
95+
| Action | Risk Level
96+
97+
| `git reset --hard`
98+
| High
99+
100+
| `git push --force`
101+
| Critical
102+
103+
| `git clean -fd`
104+
| High
105+
|===
106+
====
107+
108+
== Inline Admonitions
109+
110+
You can also use shorter inline syntax:
111+
112+
NOTE: Short notes can be written inline.
113+
114+
TIP: Quick tips are great for brevity.
115+
116+
WARNING: Brief warnings catch attention.

0 commit comments

Comments
 (0)