xrmverse
Documentation menu

Website

← xrmverse documentation

The public website of xrmverse is a static site published with GitHub Pages: a home page with one call to action (the Microsoft AppSource offer) and the Docs section, generated from the pages in this docs/ folder.

What is published

Source Published as
site/site.config.json, site/assets/ The home page (index.html), the logo, the favicon, the stylesheet and the Sora font
docs/*.md, except the pages listed in unpublished One page each under docs/<page>.html
docs/images/ Only the images that published pages show or link to
README.md, section "Documentation" The groups and order of the Docs menu and the Docs index page
  • docs/superpowers/ (specs, plans, checklists) is internal and is never published.
  • A page can be kept off the site by listing its file name (without .md) in unpublished in site/site.config.json. Today: status, azure-marketplace, development. The page stays in the repository, readable on GitHub; it is not built, not listed in the menu or the index, and its row in the README table is skipped.
  • repositoryPublic in site/site.config.json says whether the GitHub repository is public. While it is false, links to repository files, issues and pull requests would show visitors a 404, so they are dropped too and there is no "View this page on GitHub" link.
  • A page in docs/ that is not listed in the README's Documentation table still gets published, in a "More" group at the end of the menu. Add it to the table to place it.
  • A link to internal material (an unpublished page, docs/superpowers/ or, while repositoryPublic is false, anything on the repository) keeps its text and loses the link. As a safety net, the build fails if any generated page still links to internal material or if an unpublished page was generated.
  • Every page carries the trademark notice of the legal guardrails (§7) in its footer.

The AppSource button

The home page button reads appSourceUrl from site/site.config.json. While it is null the button shows "Coming soon on Microsoft AppSource" and goes nowhere. When the offer is published, set the offer URL there; the button then reads "Get it on Microsoft AppSource" and links to it.

Building locally

cd site && npm ci && cd ..
node site/build.mjs _site     # writes the site into _site/

Open _site/index.html in a browser. Links are relative, so the site works from disk, from https://<org>.github.io/<repo>/ and from a custom domain alike. Diagrams written as ```mermaid blocks are rendered in the browser by Mermaid, loaded from jsDelivr only on the pages that have one.

Deployment

The workflow .github/workflows/pages.yml builds and deploys the site on every push to main that changes docs/ (except docs/superpowers/), README.md, site/ or the workflow itself, and on demand (Run workflow). It runs two short jobs; it does not build or test the server.

One-time setup by a repository admin: Settings → Pages → Build and deployment → Source: GitHub Actions.

GitHub Pages sites are public on the internet, even when the repository is private (unless the organization uses GitHub Enterprise Cloud with private Pages). Everything in docs/ except docs/superpowers/ and the unpublished pages becomes public once the site is enabled. Mentions of internal files in the text of a published page (for example the path of an acceptance checklist) are still visible as plain text.

Style

Minimal and monochrome: lots of white space, a centred hero, a top bar with the logo and Docs, a left menu and an "On this page" outline. Colours come from the Indigo palette of the web admin (ui/src/shell/theme.ts); the font is Sora, the font of the xrmverse logo, self-hosted under the SIL Open Font License 1.1 (site/assets/fonts/OFL-Sora.txt). Light and dark mode follow the system setting.