Craft Wiki
Craft Wiki is the documentation site for ArtCraft Studio and the Craft Apps, published at craft.wiki. The site is generated as static HTML and edited in GitHub or through a self-hosted Sveltia CMS interface.
How it fits together
- Contributors edit Markdown files in this repository, either directly or through the visual editor.
- Astro and Starlight turn those files into a static site in
dist/. The build also bundles the Sveltia editor into the site. - A push to
mainruns a GitHub Actions workflow that calls a Cloudflare deploy hook. - Cloudflare Workers Builds checks out the repository, runs the build, and deploys the generated files as static assets. The Worker serves the public site and editor and handles Discord sign-in; it does not need a database.
The Cloudflare hook workflow succeeding means Cloudflare accepted the hook request. Check the Worker's build history separately to confirm that the build and deployment succeeded.
Repository layout
astro.config.mjs Starlight configuration and app sidebar groups
src/content.config.ts Starlight content collection and schema
src/content/docs/index.mdx Home page, hero copy, and app cards
src/content/docs/apps/ Markdown pages, one folder per app
src/data/apps.mjs App names, slugs, icon extensions, and shared guides
src/lib/appSidebar.mjs Builds each app's sidebar links from its pages
src/routeData.mjs Sets app pages' previous and next links from the sidebar
src/components/ Custom header, sidebar, page title, and theme
src/styles/custom.css Wiki theme and layout
public/assets/apps/ App icons used by the site
public/assets/uploads/ Images uploaded through the editor, when present
public/edit/index.html Editor sign-in guidance
public/admin/index.html Sveltia CMS entry point
public/admin/config.yml GitHub backend and app collections
scripts/prepare-cms.mjs Copies the installed CMS bundle into public assets
wrangler.jsonc Cloudflare Worker configuration
worker/index.js Discord sign-in and the editor's GitHub route
.github/workflows/deploy.yml GitHub Actions deploy-hook trigger
dist/, .astro/, node_modules/, and public/admin/vendor/ are generated and are not committed. The editor bundle is installed from the pinned npm dependency and copied into public/admin/vendor/ by the build; the deployed editor does not depend on a CMS CDN.
Local development and builds
Use Node.js 22.23.4 or newer and npm 9.6.5 or newer. The repository's .nvmrc selects Node 22; ensure the installed Node 22 release meets Astro's minimum version.
npm ci
npm run dev
Astro prints the local development URL. To prepare the editor bundle before using /admin/ locally, run node scripts/prepare-cms.mjs after installing dependencies, or run a production build first:
npm run build
npm run preview
npm run build copies the Sveltia bundle, then runs astro build. Starlight renders the content collection to dist/, builds a Pagefind search index, and emits a sitemap. npm run preview serves that generated output locally. The custom sidebar's search field filters app names; it is separate from the Pagefind index.
Documentation content
App guides are Markdown files under src/content/docs/apps/<app-slug>/. Their paths determine their URLs. For example, src/content/docs/apps/photocraft/getting-started.md is published at /apps/photocraft/getting-started/.
Each app currently has five pages:
overview.mdgetting-started.mdinstall-update.mdworkflows.mdtroubleshooting.md
Pages start with YAML frontmatter for Starlight. The visual editor exposes the title, optional description, sidebar section, sidebar order, and Markdown body. Choosing Workflows in the Sidebar section field sets parent: workflows, so the sidebar lists the page under Workflows; a page with the field left empty is listed at the top level. The editor leaves empty optional fields out of the frontmatter:
---
title: Getting started
description: Getting started with PhotoCraft.
---
Write the guide here.
Use Markdown headings, links, lists, images, and code blocks for the content. Images uploaded through the editor are committed under public/assets/uploads/ and served from /assets/uploads/. The existing app icons live under public/assets/apps/.
Starlight uses the docsLoader() and docsSchema() in src/content.config.ts to load and validate content. A malformed frontmatter field or unsupported schema value can fail the build. Check the Astro build output when adding metadata or MDX components.
Adding or reorganizing an app
The navigation and home page have a small amount of explicit configuration. To add an app:
- Create its Markdown pages under
src/content/docs/apps/<slug>/and add its icon topublic/assets/apps/. - Add its slug, display name, and any non-default icon extension to
src/data/apps.mjs, and add an official app's slug to its category inappCategoriesthere.WikiSidebar.astrouses these lists to render the icon and expandable group under its category; the build stops if an official app has no category. - Add a matching app group in
astro.config.mjsand a collection inpublic/admin/config.ymlso Starlight and Sveltia can find its pages. - Add an icon card to the same category in
src/content/docs/index.mdxand update its app count. - Run
npm run buildand check the home page, app links, and/admin/.
The custom sidebar lists every page in an app's folder. src/lib/appSidebar.mjs reads the pages and sorts them by sidebar.order, then by title. A page without sidebar.order comes after the pages that have one, and Troubleshooting is always last. The link text is the page's sidebar.label when it has one, Overview for overview.md, and the page title otherwise. A page with sidebar.hidden: true is left out, and so is a page with draft: true when Astro builds in production mode.
To nest a page under another page of the same app, set parent to that page's file name without .md. For example, VectorCraft's task guides set parent: workflows. The sidebar lists these pages under the parent's link, sorted the same way, and expands the list on the parent and on each of its pages. A parent must be a page without a parent of its own; the build stops when parent names any other page. The previous and next links at the foot of an app page follow the same order: src/routeData.mjs sets them from the custom sidebar unless the page sets prev or next in its frontmatter. The guides list in src/data/apps.mjs gives the order of the five shared pages when they have no sidebar.order.
Visual editor
The header's Edit wiki link opens /edit/, which explains sign-in and links to /admin/. Sveltia CMS is a browser-based visual editor for the app collections in public/admin/config.yml. Choose an app, select a page, edit its title, description, sidebar section, sidebar order, and body, then save. The editor uses GitHub as its backend and the configured branch is main.
Discord sign-in
Anyone with the Senior Contributor role in the ArtCraft Discord server can edit the wiki. In /admin/ they choose Sign In Using Discord. They need no GitHub account or token.
The CMS hardcodes its sign-in labels and offers no option to rename them, so scripts/prepare-cms.mjs rewrites both in the generated bundle: the top button reads Sign In Using Discord and starts the Worker's Discord sign-in, and the lower one reads Sign In Using GitHub Access Token. The build fails if a bundle update drops either label.
worker/index.js handles this:
/api/authsigns the person in with Discord and checks the role inDISCORD_ROLE_ID. It issues a signed session that lasts 8 hours, so someone who loses the role keeps access until it expires. Discord may finish in a new tab, for example after handing off to its desktop app, so the page then saves the session itself and opens/admin/./api/github/is the editor's GitHub API. Sessions use an installation token from the Craft Wiki GitHub App (or legacyGITHUB_TOKEN), which never reaches the browser. They can read the repository and can commit only tosrc/content/docs/apps/andpublic/assets/uploads/onmain. Each commit body names the Discord user, because the commit itself belongs to the GitHub App (Craft Wiki[bot]).- GitHub tokens from maintainers and contributors pass through this route unchanged and are not stored.
The Discord application is ArtCraft FredBot. Its OAuth2 settings need the redirect https://craft.wiki/api/auth/callback. The bot itself does not need to run. The IDs are in wrangler.jsonc, and these Worker secrets are set in Cloudflare, never in this repository:
| Secret | Value |
|---|---|
DISCORD_CLIENT_SECRET |
The application's OAuth2 client secret |
GITHUB_APP_ID |
The Craft Wiki GitHub App ID |
GITHUB_APP_INSTALLATION_ID |
The GitHub App installation ID on storytold/craft-wiki |
GITHUB_APP_PRIVATE_KEY |
The GitHub App's private key PEM (PKCS#1 or PKCS#8) |
SESSION_SECRET |
A long random value. Changing it signs everyone out |
Setting GITHUB_TOKEN (fine-grained personal access token with Contents: Read and write) is also supported as a fallback if the GitHub App secrets are not set.
Until they are set, the button reports that sign-in is not configured and token sign-in keeps working. Run the Worker's tests with node --test worker/index.test.mjs.
GitHub access and token
Maintainers with write access to storytold/craft-wiki can use a fine-grained personal access token:
- In GitHub, create a fine-grained personal access token owned by the appropriate account or organization.
- Under repository access, choose Only select repositories and select
storytold/craft-wiki. No other repository is required. - Set repository permission Contents to Read and write. GitHub adds read-only Metadata access automatically. The organization may need to approve the token.
- Open
/admin/, choose Sign In Using GitHub Access Token, and provide the token in the editor. Do not commit tokens to the repository.
Community contributors without write access can use a classic personal access token with the public_repo scope for this public repository. This scope covers public repositories accessible to that GitHub account, including the contributor's fork; it cannot be restricted to storytold/craft-wiki alone. The editor prompts contributors to create or reuse a fork. See Sveltia's open-authoring documentation for current requirements.
Sveltia stores its sign-in token in the browser's local storage and reaches GitHub through the Worker's /api/github/ route. See Sveltia's GitHub backend documentation for current token and authentication details.
Open authoring and review
Open authoring is enabled in the backend, with editorial_workflow as the top-level publish mode. The app collections opt into simple mode for maintainers, so people with write access still save directly to main. A protected branch can prevent direct saves for users who cannot push to it.
For contributors without write access, Sveltia creates or reuses their fork and saves each draft on a branch there. Saving a draft alone does not open a pull request: choose Send for Review or move the entry to In Review to create a PR against main. Maintainers review and merge that PR on GitHub; merging triggers the normal deployment. Contributors do not need write access to storytold/craft-wiki, and a draft does not go live until it is merged.
The public repository allows forks. If a contributor's fork has become stale and the CMS cannot synchronize workflow files, they can sync the fork on GitHub before trying again. The configuration deliberately does not request the broad workflow scope.
GitHub OAuth is not configured: the editor's top sign-in button goes to Discord through this Worker.
What can be edited visually
The app guide collections under src/content/docs/apps/ are available in Sveltia. The homepage's MDX layout, app cards, app list, and theme are maintained in the repository code rather than in the visual editor. /admin/ is a content editor, not an inline page-layout editor.
Layout and theme
The site uses Astro Starlight with custom components configured in astro.config.mjs:
WikiHeader.astrorenders the Craft Wiki brand and navigation, including the edit link.WikiSidebar.astrorenders the searchable app list, each app's icon, and expandable guide links. The current app is expanded on its pages.WikiPageTitle.astrohides the default Starlight page title on the custom home page and retains it on guide pages.WikiThemeProvider.astrostarts in dark mode and restores the visitor's saved light or dark choice.
src/styles/custom.css styles the layout and uses the Archivo, Instrument Serif, Inter, and Geist Mono font families to match the main ArtCraft site. Font files are npm dependencies and are bundled during the build. The homepage markup and its hero copy live in src/content/docs/index.mdx.
Cloudflare deployment
The current site uses Cloudflare Workers static assets with a small Worker for /api/*. wrangler.jsonc names the Worker craft-wiki, points its assets directory at ./dist, and sets worker/index.js as its entry point. The Cloudflare build settings should use:
- Production branch:
main - Root directory: repository root (leave blank)
- Build command:
npm run build - Deploy command:
npx wrangler deploy - Preview command:
npx wrangler preview
The Worker name in Cloudflare must match the name in wrangler.jsonc. craft.wiki must be configured as a custom domain on the Worker in Cloudflare. The repository does not create or manage the Cloudflare account, domain, or Git connection.
For the current hook-based deployment, the repository Actions variable CLOUDFLARE_DEPLOY_HOOK contains the Cloudflare build hook URL. .github/workflows/deploy.yml calls it on pushes to main; it can also be run using Actions → Trigger Cloudflare deploy → Run workflow. It needs no repository checkout or GitHub write permissions. If the hook changes, update the variable in GitHub repository → Settings → Secrets and variables → Actions → Variables.
If Cloudflare's own Git integration also triggers production builds on every push, the hook workflow can cause an additional build. Choose the trigger arrangement that matches the Cloudflare project settings.
Troubleshooting deployments
- If the workflow fails immediately, check that
CLOUDFLARE_DEPLOY_HOOKexists and that the hook is active. - If the hook succeeds but the site is unchanged, inspect Workers & Pages → craft-wiki → Deployments → View Build History. Confirm the build used the intended
maincommit and completed successfully. - If the old site remains visible, check the Worker/domain routing and the currently deployed version. The GitHub Actions result alone does not confirm which Cloudflare version is live.
- If
/admin/fails to load, check that the build copiedpublic/admin/vendor/and thatdist/admin/index.html,dist/admin/config.yml, and the CMS bundle exist. - If editor sign-in fails, check the token type and scope, and any organization approval. Maintainers need repository write access; contributors instead need permission to create a fork. If saving fails after a successful login, check branch protection, fork synchronization, and the build history.
Safe Browsing status
Chrome's warning comes from Google's Safe Browsing verdict for craft.wiki, and a partial listing (status 3) only covers some pages, so the site can look fine while the sign-in URLs warn. npm run check:safebrowsing prints the verdict and exits non-zero when the site is listed; .github/workflows/safebrowsing.yml runs it daily and on demand from Actions → Check Safe Browsing status. When it fails, open Security issues in Search Console for the sample URLs and request a review there: the listing clears only after Google reviews it.