- MDX 51%
- JavaScript 25.2%
- Astro 18.6%
- TypeScript 3%
- CSS 1.7%
- Other 0.5%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| .forgejo/workflows | ||
| public | ||
| release-notes | ||
| scripts | ||
| src | ||
| wiki | ||
| .dockerignore | ||
| .gitignore | ||
| astro.config.mjs | ||
| Dockerfile | ||
| nginx.conf | ||
| package-lock.json | ||
| package.json | ||
| README.md | ||
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 ofplatform.wiki(committed; refreshed by the sync workflow). Never hand-edit here; edit the wiki.release-notes/: copies ofplatform/.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.mdlinks to final URLs, copies assets, generates the sidebar from_Sidebar.md+ the curated groups inscripts/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
latesttree; releases section covers changes). - i18n (English only for now).
- Moving content into this repo; the wiki remains where docs are written.