Skip to content
OpenGISPublic

About

Keeping it classy.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Open GIS Branding

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.

❤️ AI ❤️

Quick start (consumers)

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.

Local development

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 verifies

npm 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.

Project structure

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

Documentation pipeline

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 page
  • public/docs/*.md — byte-for-byte copies of the source docs
  • public/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.

Hosted consumer assets

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.

Build and deployment

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.

Testing and screenshots

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 screenshots

Full-page Open GIS styleguide in dark mode Full-page Open GIS styleguide in light mode

Screenshots are tracked in git so visual changes appear in review diffs. See screenshots/ for the per-band captures.

Dependencies and licence

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:

MIT — see LICENSE.

Documentation

About

Keeping it classy.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Contributors

Languages