docs: v3-first documentation, v2 archived under a legacy section

.github/workflows/reference-checks.yml

@@ -0,0 +1,62 @@
+name: Reference checks
+on:
+  pull_request:
+  schedule:
+    - cron: '0 6 * * 1'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  cli-commands:
+    name: CLI command reference
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Setup Node
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 24
+
+      - name: Download the latest v3 CLI
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          tag=$(gh release list -R spicetify/cli --exclude-drafts --limit 100 \
+            --json tagName --jq '[.[] | select(.tagName | startswith("v3."))][0].tagName')
+          if [ -z "$tag" ]; then echo "No v3 release found" >&2; exit 1; fi
+          echo "Using spicetify/cli $tag"
+          asset="spicetify-${tag#v}-linux-x86_64.tar.zst"
+          mkdir -p "$RUNNER_TEMP/cli"
+          cd "$RUNNER_TEMP/cli"
+          gh release download "$tag" -R spicetify/cli -p "$asset" -p "$asset.sha256"
+          echo "$(cat "$asset.sha256")  $asset" | sha256sum -c -
+          tar --zstd -xf "$asset" spicetify
+
+      - name: Check CLI command reference
+        run: node scripts/check-cli-commands.mjs "$RUNNER_TEMP/cli/spicetify"
+
+  api-wrapper:
+    name: API wrapper reference
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+
+      - name: Setup Node
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Check API wrapper reference
+        run: pnpm run check:api-wrapper

.husky/pre-commit

@@ -1 +1 @@
-bun lint-staged
+pnpm exec lint-staged

README.md

@@ -1,7 +1,21 @@
-# Spicetify Docs
+# Spicetify docs
 
-This repository holds the documentation for Spicetify, which can be found [here](https://spicetify.app).
+This repository is the source of [spicetify.app](https://spicetify.app), built with Astro. Pages are Markdown files in `src/content/docs`, and the sidebar is in `src/config/sidebar.ts`.
 
-## Contributing
+To run the site locally, install the dependencies with pnpm and start the dev server:
 
-If you feel like you can contribute, please do so by opening an issue or pull request. We are always open to expand our documentation and add new features.
+```bash
+pnpm install
+pnpm dev
+```
+
+To fix or add a page, open an issue or a pull request.
+
+## Reference checks
+
+Two scripts check that the reference pages match the code, and the `Reference checks` workflow runs them on every pull request and weekly:
+
+- `pnpm run check:cli-commands <path-to-spicetify>` compares `src/content/docs/cli/commands.md` with the commands in the binary's `--help`. CI uses the Linux x86_64 build of the newest v3 release, which includes the Linux-only `spotify` commands.
+- `pnpm run check:api-wrapper [path-or-url]` compares the `development/api-wrapper` pages with the members of `declare namespace Spicetify` in the CLI's `globals.d.ts`, fetched from the `v3-beta` branch by default.
+
+The rules each check uses, and their allowlists, are at the top of the scripts in `scripts/`.

astro.config.ts

@@ -33,13 +33,36 @@ export default defineConfig({
     '/docs/blog/authors': '/blog',
     // Preserve the URL equity of the pre-2026 Docusaurus information
     // architecture. These pages moved rather than disappeared.
-    '/docs/advanced-usage': '/docs/customization',
-    '/docs/advanced-usage/installation': '/docs/getting-started',
-    '/docs/advanced-usage/uninstallation': '/docs/uninstallation',
-    '/docs/advanced-usage/command-line-interface': '/docs/cli',
-    '/docs/advanced-usage/themes': '/docs/customization/themes',
-    '/docs/advanced-usage/extensions': '/docs/customization/extensions',
-    '/docs/advanced-usage/custom-apps': '/docs/customization/custom-apps',
-    '/docs/customization/marketplace.md': '/docs/customization/marketplace',
+    '/docs/advanced-usage': '/docs/legacy/customization',
+    '/docs/advanced-usage/installation': '/docs/legacy/getting-started',
+    '/docs/advanced-usage/uninstallation': '/docs/legacy/uninstallation',
+    '/docs/advanced-usage/command-line-interface': '/docs/legacy/cli',
+    '/docs/advanced-usage/themes': '/docs/legacy/customization/themes',
+    '/docs/advanced-usage/extensions': '/docs/legacy/customization/extensions',
+    '/docs/advanced-usage/custom-apps':
+      '/docs/legacy/customization/custom-apps',
+    '/docs/customization/marketplace.md':
+      '/docs/legacy/customization/marketplace',
+    // v3 took over the main tree; every v2 page kept its content under
+    // /docs/legacy, so the old URLs point at the page they promised rather
+    // than at a v3 equivalent that says something different.
+    '/docs/customization': '/docs/legacy/customization',
+    '/docs/customization/marketplace': '/docs/legacy/customization/marketplace',
+    '/docs/customization/themes': '/docs/legacy/customization/themes',
+    '/docs/customization/extensions': '/docs/legacy/customization/extensions',
+    '/docs/customization/custom-apps': '/docs/legacy/customization/custom-apps',
+    '/docs/customization/config-file': '/docs/legacy/customization/config-file',
+    '/docs/development/themes': '/docs/legacy/development/themes',
+    '/docs/development/extensions': '/docs/legacy/development/extensions',
+    '/docs/development/custom-apps': '/docs/legacy/development/custom-apps',
+    '/docs/development/js-modules': '/docs/legacy/development/js-modules',
+    '/docs/development/spicetify-creator/the-basics':
+      '/docs/legacy/spicetify-creator/the-basics',
+    '/docs/development/spicetify-creator/create-extensions':
+      '/docs/legacy/spicetify-creator/create-extensions',
+    '/docs/development/spicetify-creator/create-custom-apps':
+      '/docs/legacy/spicetify-creator/create-custom-apps',
+    '/docs/development/spicetify-creator/building-and-testing':
+      '/docs/legacy/spicetify-creator/building-and-testing',
   },
 });