Skip to content

Commit 9dd5f17

Browse files
mishraompmishraomp
committed
chore: add documentation to publish on github pages
1 parent e12d17d commit 9dd5f17

26 files changed

Lines changed: 12244 additions & 0 deletions

‎.github/workflows/pages.yml‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
name: Deploy GitHub Pages
2+
3+
# Builds the docs/ static site and deploys it to GitHub Pages. Triggers on push
4+
# to main that touches docs/** (or this workflow file), plus a manual
5+
# workflow_dispatch button. The build is deterministic: it runs bash docs/build.sh
6+
# and uploads the resulting docs/ directory as the Pages artifact.
7+
8+
on:
9+
push:
10+
branches: [main]
11+
paths:
12+
- "docs/**"
13+
- ".github/workflows/pages.yml"
14+
workflow_dispatch:
15+
schedule:
16+
- cron: "0 7 * * 0" # every Sunday at 7 AM UTC
17+
18+
# Pages deploys need pages:write + id-token:write (for the OIDC-signed
19+
# environment URL). Both jobs only read repo contents.
20+
permissions:
21+
contents: read
22+
pages: write
23+
id-token: write
24+
25+
# Allow only one Pages deployment at a time. Don't cancel in-flight runs —
26+
# letting them finish keeps the deployment history honest.
27+
concurrency:
28+
group: "pages"
29+
cancel-in-progress: false
30+
31+
jobs:
32+
build:
33+
runs-on: ubuntu-24.04
34+
steps:
35+
- name: Checkout
36+
uses: actions/checkout@v6
37+
38+
- name: Setup Node.js
39+
uses: actions/setup-node@v6
40+
with:
41+
node-version: "24"
42+
43+
- name: Build documentation
44+
run: |
45+
cd docs
46+
chmod +x build.sh
47+
./build.sh
48+
49+
- name: Setup Pages
50+
uses: actions/configure-pages@v6
51+
52+
- name: Upload artifact
53+
uses: actions/upload-pages-artifact@v4
54+
with:
55+
path: docs
56+
57+
deploy:
58+
needs: build
59+
runs-on: ubuntu-24.04
60+
environment:
61+
name: github-pages
62+
url: ${{ steps.deployment.outputs.page_url }}
63+
steps:
64+
- name: Deploy to GitHub Pages
65+
id: deployment
66+
uses: actions/deploy-pages@v5

‎README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,9 @@ Each skill is validated against a common spec on every pull request and — once
77
merged — published as a versioned **npm package** you install and upgrade with
88
tooling you already use.
99

10+
Browse the catalogue and full documentation at
11+
**<https://bcgov.github.io/agent-skills/>**.
12+
1013
---
1114

1215
## Jump to what you need

‎docs/README.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# Documentation site
2+
3+
The browsable docs for [`bcgov/agent-skills`](https://github.com/bcgov/agent-skills).
4+
Built with a **zero-dependency template engine** (Bash + a tiny Node script)
5+
and served from GitHub Pages.
6+
7+
## TL;DR
8+
9+
```bash
10+
cd docs
11+
./build.sh # build the static site + search index
12+
open index.html # macOS — use xdg-open on Linux, start on Windows
13+
```
14+
15+
## What's in here
16+
17+
```
18+
docs/
19+
├── _partials/ # Shared header + footer (injected into every page)
20+
│ ├── header.html
21+
│ └── footer.html
22+
│
23+
├── _pages/ # Source content — one file per page
24+
│ ├── _template.html # Starter for new pages (skipped by build)
25+
│ ├── index.html # Home
26+
│ ├── catalog.html # Skill catalog
27+
│ ├── consume.html # How to install a skill
28+
│ ├── contribute.html # How to add a skill
29+
│ ├── spec.html # SKILL.md spec summary
30+
│ ├── architecture.html # Pipeline & governance
31+
│ └── faq.html # FAQ
32+
│
33+
├── assets/ # Static assets shipped as-is
34+
│ ├── bc_citz_logo.jpg
35+
│ ├── favicon.svg
36+
│ ├── search.js # FlexSearch client wiring
37+
│ └── search-index.json # Generated — full-text search index
38+
│
39+
├── build.sh # Template engine + search index trigger
40+
├── generate-search-index.js # Node — parses built HTML → search-index.json
41+
├── README.md # This file
42+
│
43+
└── *.html # Build output, served by GitHub Pages
44+
```
45+
46+
## How the template engine works
47+
48+
Each page in `_pages/` starts with two HTML comments that the build script reads:
49+
50+
```html
51+
<!-- TITLE: My Page Title -->
52+
<!-- NAV: catalog -->
53+
54+
<h1>Page content starts here</h1>
55+
```
56+
57+
| Metadata | What it does |
58+
| -------- | ----------------------------------------------------------- |
59+
| `TITLE` | Substituted into the `<title>` tag and the visible heading |
60+
| `NAV` | Marks the matching nav item as `active` (uppercased: `NAV_CATALOG`) |
61+
62+
`build.sh` then concatenates `_partials/header.html` + page content + `_partials/footer.html`, replaces `{{PAGE_TITLE}}`, `{{NAV_*}}`, and `{{YEAR}}`, and writes the assembled HTML next to itself at `docs/<page>.html`.
63+
64+
After all pages are written, the script invokes `generate-search-index.js`, which:
65+
66+
1. Walks every `*.html` at the docs root.
67+
2. Auto-assigns `id=` attributes to any `h1`/`h2`/`h3` missing one (so deep-links work).
68+
3. Writes `assets/search-index.json`, consumed in the browser by [FlexSearch](https://github.com/nextapps-de/flexsearch) (loaded from a CDN by `assets/search.js`).
69+
70+
## Adding a new page
71+
72+
1. **Create the source file** at `_pages/<slug>.html`:
73+
74+
```html
75+
<!-- TITLE: My New Page -->
76+
<!-- NAV: mynewpage -->
77+
78+
<h1>My New Page</h1>
79+
<p>Use any HTML. The header bundles all CSS.</p>
80+
```
81+
82+
2. **Add a nav link** in `_partials/header.html`:
83+
84+
```html
85+
<a href="mynewpage.html" class="{{NAV_MYNEWPAGE}}">My New Page</a>
86+
```
87+
88+
3. **Add the clear-line** in `build.sh` so inactive instances render blank:
89+
90+
```bash
91+
header="${header//\{\{NAV_MYNEWPAGE\}\}/}"
92+
```
93+
94+
4. **Build and check**:
95+
96+
```bash
97+
./build.sh
98+
open mynewpage.html
99+
```
100+
101+
The build is fast enough (milliseconds) that there's no watch mode — just re-run `./build.sh`.
102+
103+
## Available CSS classes
104+
105+
The header bundles a small in-house framework — no Tailwind, no external CSS. See `_pages/_template.html` for a live cheat-sheet covering:
106+
107+
- **Layout** — `.grid` / `.grid-2` / `.grid-3` / `.grid-4`
108+
- **Components** — `.card`, `.card-gold`, `.alert .alert-info|alert-warning|alert-success`, `.badge .badge-gold|badge-blue`
109+
- **Interactive** — `.card-link`, `.card-arrow`, `.feature-icon`, `.hero`
110+
- **Typography** — `h1`–`h3` styled defaults, `code`, `pre`, `table`
111+
112+
## Deployment
113+
114+
GitHub Pages runs `./build.sh` on every push to `main` that touches `docs/**` and publishes the output. The workflow lives at `.github/workflows/pages.yml`.
115+
116+
## Why Bash instead of Jekyll/Hugo/etc?
117+
118+
1. **Tiny footprint** — Bash + Node, no plugin ecosystem to keep alive.
119+
2. **Runs anywhere** — laptop, WSL, GitHub Actions runner.
120+
3. **Easy to read** — `build.sh` is ~100 lines of plain shell.
121+
4. **Fast** — full rebuild in milliseconds.
122+
5. **GitHub Pages native** — no custom build action required beyond `bash`.

0 commit comments

Comments
 (0)