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

  1. Contributors edit Markdown files in this repository, either directly or through the visual editor.
  2. Astro and Starlight turn those files into a static site in dist/. The build also bundles the Sveltia editor into the site.
  3. A push to main runs a GitHub Actions workflow that calls a Cloudflare deploy hook.
  4. 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.md
  • getting-started.md
  • install-update.md
  • workflows.md
  • troubleshooting.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:

  1. Create its Markdown pages under src/content/docs/apps/<slug>/ and add its icon to public/assets/apps/.
  2. 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 in appCategories there. WikiSidebar.astro uses these lists to render the icon and expandable group under its category; the build stops if an official app has no category.
  3. Add a matching app group in astro.config.mjs and a collection in public/admin/config.yml so Starlight and Sveltia can find its pages.
  4. Add an icon card to the same category in src/content/docs/index.mdx and update its app count.
  5. Run npm run build and 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:

  1. /api/auth signs the person in with Discord and checks the role in DISCORD_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/.
  2. /api/github/ is the editor's GitHub API. Sessions use an installation token from the Craft Wiki GitHub App (or legacy GITHUB_TOKEN), which never reaches the browser. They can read the repository and can commit only to src/content/docs/apps/ and public/assets/uploads/ on main. Each commit body names the Discord user, because the commit itself belongs to the GitHub App (Craft Wiki[bot]).
  3. 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:

  1. In GitHub, create a fine-grained personal access token owned by the appropriate account or organization.
  2. Under repository access, choose Only select repositories and select storytold/craft-wiki. No other repository is required.
  3. Set repository permission Contents to Read and write. GitHub adds read-only Metadata access automatically. The organization may need to approve the token.
  4. 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.astro renders the Craft Wiki brand and navigation, including the edit link.
  • WikiSidebar.astro renders the searchable app list, each app's icon, and expandable guide links. The current app is expanded on its pages.
  • WikiPageTitle.astro hides the default Starlight page title on the custom home page and retains it on guide pages.
  • WikiThemeProvider.astro starts 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_HOOK exists 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 main commit 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 copied public/admin/vendor/ and that dist/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.

S
Description
Documentation wiki for ArtCraft and the Craft Apps.
Readme
76 MiB
0 Stars 1 Watchers 0 Forks
Languages
JavaScript 36.1%
CSS 25.3%
Astro 18.6%
MDX 14.8%
HTML 3.9%
Other 1.3%