Documentation, live styleguide and hosted consumer assets for the Open GIS brand.
The numbered Markdown in docs/ is the source of truth. The Nuxt site renders it at https://www.ogis.org/branding/ with live component and logo demos, publishes the raw Markdown for agents, and hosts the stylesheet and JavaScript that consumers load directly.
One stylesheet carries Pico CSS, the Open GIS theme and the highlight.js syntax palette:
<link rel="stylesheet" href="https://www.ogis.org/branding/assets/css/ogis.css" />Highlighted code needs a highlight.js runtime, supplied by the consumer:
<script src="/your/highlight.min.js"></script>
<script>
hljs.highlightAll();
</script>Paint a decorative random-country map into any sized block:
<div data-background-map style="height: 220px"></div>
<script src="https://www.ogis.org/branding/assets/js/background-map.js" defer></script>The CSS bundles Pico CSS and the theme tokens, so no separate Pico request is needed. The default logo is a self-contained snippet at assets/html/logo.html. For the full asset list, logo variants and options, see docs/1.quick-start.md.
Node 24 (see .nvmrc) and npm:
npm install
npm run dev # build docs and consumer assets, then start Nuxt dev
npm run build # generate the static site, then verify the output
npm run preview # serve the generated site
npm test # Playwright smoke suite
npm run format # Prettier write; format:check verifiesnpm run dev builds the generated docs once at startup. While it runs, use npm run docs:watch (or rerun npm run build:docs) after editing Markdown so app/data/docs.json, public/docs/ and public/llms.txt stay current.
| Path | Purpose |
|---|---|
app/ |
Nuxt 4 application: page, components, composables, plugins and site-only styleguide CSS |
docs/ |
Numbered Markdown source and documentation index |
scss/ |
Theme source: tokens, layout, components, Pico overrides and the highlight.js palette |
src/ |
theme.js entry, UI modules and background-map/ source |
scripts/ |
Documentation, theme, export, preview and verification scripts |
public/ |
Authored logo assets plus generated docs, llms.txt and consumer assets (gitignored) |
tests/ |
Playwright end-to-end smoke suite |
screenshots/ |
Playwright page and per-band captures, tracked in git |
Numbered docs/<number>.<slug>.md files are the source of truth. Each file carries frontmatter (git_hash, modified, title, description) and exactly one H1 matching the title. An optional <!-- demo --> marker splits the rendered Markdown around a live demo.
npm run build:docs writes:
app/data/docs.json— ordered sections consumed by the Nuxt pagepublic/docs/*.md— byte-for-byte copies of the source docspublic/llms.txt— a compact machine-readable index for agents
Important
Generated outputs are gitignored. Do not edit app/data/docs.json, public/docs/ or public/llms.txt by hand.
The homepage renders the docs with live demos, while the raw Markdown and llms.txt are published for agents. See docs/README.md for the reading order.
Paths are relative to the deployment base, https://www.ogis.org/branding/.
| Path | Contract |
|---|---|
assets/css/ogis.css |
Single stylesheet: Pico CSS 2.1.1, theme tokens/components and the highlight.js palette |
assets/js/background-map.js |
IIFE exposing window.BackgroundMap (init() and refresh()); loads jQuery and Waymark-JS at runtime |
assets/html/logo.html |
Self-contained logo snippet and link |
assets/img/logo-white.svg, logo-black.svg, logo-green.png |
Logo files for dark, light and favicon/raster use |
npm run build:assets runs build:theme and build:exports: the first compiles src/theme.js through Vite into the single ogis.css, and the second bundles each entry in vite.exports.config.js as an IIFE into public/assets/js/.
Warning
public/assets/css/ogis.css and public/assets/js/background-map.js are generated and gitignored. Edit scss/, src/theme.js or src/background-map/ instead. The logo files under public/assets/html/ and public/assets/img/ are authored assets.
npm run build builds the docs and consumer assets, runs nuxt generate, then runs npm run verify:build. The verifier checks the static output for the homepage markup, published docs, llms.txt, the consumer CSS/JS contract and the logo files; a missing artefact fails the build.
GitHub Pages deploys on pushes to master through .github/workflows/pages.yml:
| Setting | Value |
|---|---|
NUXT_APP_BASE_URL |
/branding/ |
NUXT_PUBLIC_SITE_URL |
https://www.ogis.org/branding/ |
NITRO_PRESET |
github_pages |
The workflow uses Node 24 and uploads ./.output/public. Locally, .env.example documents NUXT_PUBLIC_SITE_URL (the canonical URL, generated doc URLs and llms.txt) and the optional NUXT_APP_BASE_URL for sub-path deployments.
The Playwright suite runs Chromium against its own Nuxt dev server on port 11010, with NUXT_IGNORE_LOCK=1 set for that server so it can run alongside an existing dev server on another port. It checks the rendered page, client initialisation, theme switching, the naming guard and the published routes (/llms.txt, raw docs, consumer CSS/JS and logo assets). It also captures screenshots/light-home.jpg and screenshots/dark-home.jpg, plus one light-theme image per band.
npx playwright install chromium # one-time browser install
npm test # run the suite and regenerate screenshotsScreenshots are tracked in git so visual changes appear in review diffs. See screenshots/ for the per-band captures.
Consumers:
- Pico CSS 2.1.1 — bundled into
ogis.css. - highlight.js 11.12.0 — consumer-supplied runtime; the palette ships in
ogis.css. - jQuery 3.7.1 and Waymark-JS v1 — loaded by the background map only.
Build:
- Nuxt 4, Vite and SASS.
markedandmarked-alert— build-only Markdown rendering.- Playwright and Prettier.
MIT — see LICENSE.

