No description https://docs.vski.ai
  • MDX 51%
  • JavaScript 25.2%
  • Astro 18.6%
  • TypeScript 3%
  • CSS 1.7%
  • Other 0.5%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-16 12:00:06 +00:00
.forgejo/workflows update docs 2026-11-04 18:03:03 +01:00
public update docs 2026-11-12 23:31:44 +01:00
release-notes docs: sync the wiki and the v0.18.0 release notes 2026-11-15 18:50:25 +01:00
scripts docs: sync the wiki and the v0.18.0 release notes 2026-11-15 18:50:25 +01:00
src docs: sync the wiki and the v0.18.0 release notes 2026-11-15 18:50:25 +01:00
wiki sync: wiki + release notes (cb7791d1b61dc9a2beb40ba816f781294432d197) 2026-11-16 12:00:06 +00:00
.dockerignore docs.vski.sh: Starlight docs site generated from platform.wiki 2026-11-01 18:15:50 +01:00
.gitignore docs.vski.sh: Starlight docs site generated from platform.wiki 2026-11-01 18:15:50 +01:00
astro.config.mjs update docs 2026-11-06 18:49:09 +01:00
Dockerfile kwh 2026-11-02 06:57:38 +01:00
nginx.conf init 2026-11-01 21:05:21 +01:00
package-lock.json update docs 2026-11-06 18:49:09 +01:00
package.json update docs 2026-11-06 18:49:09 +01:00
README.md update docs 2026-11-04 18:03:03 +01:00

docs.vski.ai

The VSKI documentation site: an Astro + Starlight static site whose content is generated automatically from the wiki (x/platform.wiki).

The wiki stays the single source of truth: keep editing it in Forgejo. This repo copies it in, transforms it, and deploys.

How it works

x/platform.wiki ──┐
                  │  sync-wiki workflow (every 6h + dispatch button)
x/platform ┈┈┈┈┈┈┈┤  refreshes wiki/ + release-notes/ in this repo
.release/*.md ┘  and redeploys on change
                        │
                        ▼
        scripts/sync-wiki.mjs  (also runs inside the Docker build)
        wiki/*.md ──► src/content/docs/*.md   (+ frontmatter, links, sidebar)
        release-notes/*.md ──► /releases/
                        │
                        ▼
        Astro + Starlight build ──► static site ──► nginx ──► Dokku app `docs`
  • wiki/ — raw copy of platform.wiki (committed; refreshed by the sync workflow). Never hand-edit here; edit the wiki.
  • release-notes/: copies of platform/.release/*.md (changelog section; docs/release/ before the v0.16 repo restructure — the sync script and workflow accept both).
  • scripts/sync-wiki.mjs: the generation engine. Injects frontmatter (title/description/editUrl), strips the body H1, rewrites ./Page.md links to final URLs, copies assets, generates the sidebar from _Sidebar.md + the curated groups in scripts/groups.mjs, and validates that everything resolves. Unknown new wiki pages land under a "Reference" group with a warning instead of breaking the build.
  • src/content/docs/ (top level + releases/), src/sidebar.generated.mjs, public/assets/ is generated output, owned by the script. Site-authored content (future guides, interactive pages) goes in new subdirectories, e.g. src/content/docs/guides/, which the sync never touches.
  • src/pages/index.astro: the custom landing page (dark, standalone, outside the Starlight layout).

Local development

npm install
npm run dev            # sync + astro dev server

The first sync needs content inputs. Either copy them from a local platform checkout:

WIKI_DIR=../platform/platform.wiki RELEASE_DIR=../platform/.release npm run sync

or fetch from Forgejo (ssh; GIT_REMOTE_BASE=https://x:TOKEN@vski.sh/x for CI):

npm run sync:fetch

Then open http://localhost:4321.

Deployment

Standard Dokku pattern, same as the other static sites: push to main → .forgejo/workflows/deploy.yml runs on the self-hosted runner (which is the Dokku host) → dokku git:sync --build-if-changes docs ssh://git@vski.sh/x/docs.git builds the root Dockerfile (node builder → nginx:alpine) and redeploys.

Wiki edits cannot trigger Actions directly (Forgejo wiki repos have no Actions), so .forgejo/workflows/sync-wiki.yaml runs on a 6-hour schedule and via workflow_dispatch. Use the dispatch button for an instant deploy after editing the wiki. A sync with no changes is a no-op. All the repositories it touches are public, so every clone is anonymous; the FORGEJO_TOKEN secret is used only for the one authenticated push of the sync commit back to this repo.

One-time setup (already done on the server, kept for reference)

# on the dokku host:
dokku apps:create docs
dokku domains:set docs docs.vski.ai   # or whatever domain you choose
# add the shared dokku deploy key to this repo on Forgejo,
# and set the FORGEJO_TOKEN repo secret (write:repository; pushes only,
# all clones are anonymous) for the sync workflow

Let's Encrypt is enabled automatically by the deploy workflow's Ensure-App step.

Adding interactive content later

MDX and React are already wired (@astrojs/mdx, @astrojs/react). To add an interactive page: create src/content/docs/guides/demo.mdx, import a React component from src/components/, and use it. Astro islands keep the rest of the page static. Site-authored pages belong in subdirectories (guides/, …) so the wiki sync never clobbers them.

Non-goals

  • Doc versioning (single latest tree; releases section covers changes).
  • i18n (English only for now).
  • Moving content into this repo; the wiki remains where docs are written.