Publishing docs.sidedoc.app

This documentation is a VitePress site in docs/, an npm workspace of the monorepo. It builds without a schemas checkout.

Build locally

npm ci
npm run docs:dev          # live preview on http://localhost:5173
npm run docs:build        # static site in docs/.vitepress/dist/

The configuration reference is generated. After changing a setting in docker/entrypoint.sh, the Dockerfile or a build-time variable, update docker/settings.json and run:

npm run docs:settings          # regenerate the reference pages and example files
npm run docs:check-settings    # what CI runs: fails on drift or hand-edited output

CI

The root .gitlab-ci.yml runs on merge requests and on the default branch:

Job	Stage	What it does
docs-settings-check	test	node scripts/gen-settings-docs.mjs --check.
docs-build	build	npm ci, npm run docs:build; keeps docs/.vitepress/dist/ as an artifact for two weeks.
pages	deploy	Default branch only: publishes the docs-build artifact to GitLab Pages.

Download the artifact of a merge request pipeline to review the built site.

Hosting

There are two options. Use one; remove the pages job if you choose the static server.

Option 1: GitLab Pages

1. Let the pages job run on the default branch.
2. In the project, under Deploy > Pages, add the custom domain docs.sidedoc.app and create the DNS records GitLab asks for (a CNAME to the Pages host and a TXT verification record). GitLab provisions the certificate.

Pages serves foo.html for /foo, which VitePress' cleanUrls needs. GitLab Pages cannot set custom response headers.

Option 2: the xentropics static server (like sidedoc.app)

sidedoc.app is a static site on the xentropics server, managed with Ansible in the xentropics.cloud infrastructure repository under ansible/playbooks/services/xentropics/static/. Each site has a directory sites/<name>/ with:

• vars.yml: domain and webroot (for sidedoc.app: sidedoc.app, /var/www/sidedoc);
• content/: the files to publish (not in git), synced to the webroot with rsync --delete;
• snippets/*.conf: nginx snippets included in the site's server block (sidedoc.app has the Sentry tunnel, vocabulary rewrites and basic auth for /dev/).

The sync/main.yml playbook renders the vhost from roles/staticserver/templates/site.conf.j2 (HTTP to HTTPS redirect, Let's Encrypt certificate, logs per site, snippets). setup/main.yml obtains certificates for the domains listed in vars/main.yml.

An analogous sidedoc-docs site needs:

1. DNS: an A (and AAAA) record for docs.sidedoc.app pointing at the static server, wherever the sidedoc.app zone is managed.

2. Site directory sites/sidedoc-docs/ with vars.yml:

   ---
   domain: docs.sidedoc.app
   webroot: /var/www/sidedoc-docs

3. Snippet sites/sidedoc-docs/snippets/vitepress.conf, because the vhost template has no location / and VitePress uses extension-less URLs:

   location / {
       try_files $uri $uri.html $uri/ =404;
   }
   
   location /assets/ {
       expires max;
       try_files $uri =404;
   }
   
   error_page 404 /404.html;

4. Registration: add docs.sidedoc.app to staticserver_domains in vars/main.yml and the site to staticserver_sites in roles/staticserver/defaults/main.yml, as for sidedoc.

5. Certificate: run setup/main.yml once after DNS resolves.

6. Content: put the built site in sites/sidedoc-docs/content/, either by building locally or by downloading the docs-build artifact of the default branch:

   npm run docs:build
   rsync -a --delete docs/.vitepress/dist/ <ansible>/playbooks/services/xentropics/static/sites/sidedoc-docs/content/

7. Publish: from the ansible directory,

   ansible-playbook -i inventory/inventory.ini playbooks/services/xentropics/static/sync/main.yml \
     -e static_site_name=sidedoc-docs

This mirrors how app/sidedoc-frontend/scripts/deploy-sidedoc-beta.sh publishes the app: build, copy into the site's content/ directory, then run the sync playbook for that one site.