techniq · techniq · May 29, 2026 · May 29, 2026 · May 29, 2026 · May 29, 2026
diff --git a/.changeset/add-layerstack-docs.md b/.changeset/add-layerstack-docs.md
@@ -0,0 +1,5 @@
+---
+'@layerstack/docs': major
+---
+
+feat: Add `@layerstack/docs` — reusable documentation framework and tooling for LayerStack projects
diff --git a/.changeset/config.json b/.changeset/config.json
@@ -7,5 +7,5 @@
   "access": "public",
   "baseBranch": "main",
   "updateInternalDependencies": "patch",
-  "ignore": ["@layerstack/docs"]
+  "ignore": []
 }
diff --git a/.changeset/pre.json b/.changeset/pre.json
@@ -7,7 +7,7 @@
     "@layerstack/svelte-table": "1.0.0",
     "@layerstack/tailwind": "1.0.0",
     "@layerstack/utils": "1.0.0",
-    "@layerstack/docs": "1.0.1",
+    "@layerstack/docs": "0.0.0",
     "@layerstack/svelte-state": "0.0.0"
   },
   "changesets": [

diff --git a/.github/workflows/build-preview.yml b/.github/workflows/build-preview.yml
@@ -30,5 +30,5 @@ jobs:
         uses: actions/upload-artifact@v4
         with:
           name: preview-build
-          path: sites/docs/.svelte-kit
+          path: docs/.svelte-kit
           include-hidden-files: true
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -29,12 +29,14 @@ jobs:
 
       - run: pnpm --filter "./packages/*" build
 
+      # Build the docs site before `pnpm check`: it generates the `content-collections`
+      # module at build time, which the type-check then consumes.
+      - run: pnpm --filter "./docs" build
+
       - run: pnpm check
 
       - run: pnpm lint
 
       - run: pnpm test:unit
         env:
           CI: true
-
-      - run: pnpm --filter "./sites/*" build
diff --git a/.github/workflows/deploy-prod.yml b/.github/workflows/deploy-prod.yml
@@ -4,7 +4,7 @@ on:
     branches:
       - main
     paths:
-      - sites/docs/**
+      - docs/**
       - packages/**
 
 jobs:
@@ -36,5 +36,5 @@ jobs:
           githubToken: ${{ secrets.GITHUB_TOKEN }}
           projectName: layerstack
           directory: ./.svelte-kit/cloudflare
-          workingDirectory: sites/docs
+          workingDirectory: docs
           deploymentName: Production
diff --git a/.gitignore b/.gitignore
@@ -8,4 +8,11 @@ coverage/
 .env
 .DS_Store
 
+# Generated by @content-collections and the docs markdown live-code pipeline
+.content-collections/
+.live-code/
+
+# Playwright MCP run artifacts
+.playwright-mcp/
+
 test-*
diff --git a/docs/.prettierignore b/docs/.prettierignore
@@ -0,0 +1,18 @@
+.DS_Store
+node_modules
+/build
+/dist
+/.svelte-kit
+/.content-collections
+/.live-code
+/.wrangler
+/package
+.env
+.env.*
+!.env.example
+coverage/
+
+# Ignore files for PNPM, NPM and YARN
+pnpm-lock.yaml
+package-lock.json
+yarn.lock
diff --git a/sites/docs/CHANGELOG.md → docs/CHANGELOG.md b/sites/docs/CHANGELOG.md → docs/CHANGELOG.md
diff --git a/sites/docs/LICENSE → docs/LICENSE b/sites/docs/LICENSE → docs/LICENSE
diff --git a/sites/docs/README.md → docs/README.md b/sites/docs/README.md → docs/README.md
diff --git a/docs/content-collections.ts b/docs/content-collections.ts
@@ -0,0 +1,10 @@
+import { createContentConfig } from '@layerstack/docs/content-collections';
+
+export default createContentConfig({
+  // LayerStack is a multi-package monorepo; docs are authored as `reference` content
+  // organized by package under `src/content/reference/<package>/<name>.md`.
+  packageName: 'layerstack',
+  repo: 'techniq/layerstack',
+  // `docs` -> repo root `packages`
+  packagesRoot: '../packages',
+});
diff --git a/docs/mdsx.config.js b/docs/mdsx.config.js
@@ -0,0 +1,7 @@
+import { createMdsxConfig } from '@layerstack/docs/markdown/config';
+
+export const mdsxConfig = createMdsxConfig({
+  markdownComponentsPath: '@layerstack/docs/markdown/components',
+  exampleComponentPath: '$lib/components',
+  liveCodeComponent: '@layerstack/docs/markdown/components/LiveCode.svelte',
+});
diff --git a/sites/docs/package.json → docs/package.json b/sites/docs/package.json → docs/package.json
@@ -1,6 +1,6 @@
 {
-  "name": "@layerstack/docs",
-  "description": "A collection of Svelte actions, stores and general utils",
+  "name": "@layerstack/docs-site",
+  "description": "Documentation site for LayerStack",
   "author": "Sean Lynch <techniq35@gmail.com>",
   "license": "MIT",
   "private": true,
@@ -12,33 +12,34 @@
     "preview": "vite preview",
     "package": "svelte-package",
     "prepublishOnly": "svelte-package",
-    "check": "svelte-check --tsconfig ./tsconfig.json",
-    "check:watch": "svelte-check --tsconfig ./tsconfig.json --watch",
+    "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+    "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
     "lint": "prettier --check .",
-    "format": "prettier --write .",
-    "prepare": "svelte-kit sync"
+    "format": "prettier --write ."
   },
   "devDependencies": {
     "@changesets/cli": "^2.29.4",
+    "@content-collections/core": "^0.14.3",
+    "@content-collections/markdown": "^0.1.4",
+    "@content-collections/vite": "^0.2.9",
     "@fortawesome/free-solid-svg-icons": "^6.7.2",
     "@iconify-json/lucide": "^1.2.53",
+    "@iconify-json/simple-icons": "^1.2.84",
     "@sveltejs/adapter-cloudflare": "^7.0.3",
     "@sveltejs/kit": "^2.21.0",
     "@sveltejs/package": "^2.3.11",
     "@sveltejs/vite-plugin-svelte": "^5.0.3",
     "@tailwindcss/typography": "^0.5.16",
     "@tailwindcss/vite": "^4.1.5",
     "@types/d3-array": "^3.2.1",
-    "@types/prismjs": "^1.26.5",
-    "mdsvex": "^0.12.5",
+    "mdsx": "^0.0.7",
     "posthog-js": "^1.239.0",
     "prettier": "^3.5.3",
     "prettier-plugin-svelte": "^3.3.3",
     "rehype-slug": "^6.0.0",
     "svelte": "^5.28.2",
     "svelte-check": "^4.1.6",
-    "svelte-json-tree": "^2.2.0",
-    "svelte-ux": "2.0.0-next.13",
+    "svelte-ux": "2.0.0-next.22",
     "svelte2tsx": "^0.7.36",
     "tailwindcss": "^4.1.5",
     "tslib": "^2.8.1",
@@ -49,7 +50,9 @@
   },
   "type": "module",
   "dependencies": {
+    "@fontsource-variable/inter": "^5.2.8",
     "@fortawesome/fontawesome-common-types": "^6.7.2",
+    "@layerstack/docs": "workspace:*",
     "@layerstack/svelte-actions": "workspace:*",
     "@layerstack/svelte-state": "workspace:*",
     "@layerstack/svelte-stores": "workspace:*",
@@ -59,10 +62,6 @@
     "@mdi/js": "^7.4.47",
     "clsx": "^2.1.1",
     "d3-array": "^3.2.4",
-    "prism-svelte": "^0.5.0",
-    "prism-themes": "^1.9.0",
-    "prismjs": "^1.30.0",
-    "sveld": "^0.22.1",
     "tailwind-merge": "^3.2.0"
   },
   "peerDependencies": {

diff --git a/sites/docs/src/app.d.ts → docs/src/app.d.ts b/sites/docs/src/app.d.ts → docs/src/app.d.ts
@@ -1,4 +1,4 @@
-/// <reference path="../../../packages/svelte-actions/src/lib/types.d.ts" />
+/// <reference path="../../packages/svelte-actions/src/lib/types.d.ts" />
 export * from 'unplugin-icons/types/svelte';
 
 // See https://kit.svelte.dev/docs/types#app

diff --git a/sites/docs/src/app.html → docs/src/app.html b/sites/docs/src/app.html → docs/src/app.html
diff --git a/docs/src/content/guides/LLMs.md b/docs/src/content/guides/LLMs.md
@@ -0,0 +1,49 @@
+---
+title: LLMs
+description: Using the LayerStack documentation with LLMs
+order: 99
+---
+
+<script>
+  import OpenWithButton from '$lib/components/OpenWithButton.svelte';
+</script>
+
+The LayerStack documentation is designed to be useful both for human developers working alongside LLMs and for large language models ingesting the docs directly.
+
+## :icon{name="lucide:user" class="relative -top-1"} For the humans
+
+<OpenWithButton example />
+
+At the top of each documentation page — and demonstrated above — you'll find a button that copies the page's documentation as Markdown to your clipboard. The dropdown also offers handy options such as viewing the source or opening the page in a chat assistant.
+
+::note
+The `View Component source` option is only shown for pages with a linked source file.
+::
+
+## :icon{name="lucide:bot" class="relative -top-1"} For the bots
+
+LayerStack adopts the [llms.txt](https://llmstxt.org/) proposal — a structured, machine-readable format optimized for LLMs — so tools and AI systems can efficiently parse the documentation.
+
+## LLM-friendly documentation
+
+::steps
+
+### Per page
+
+Append `/llms.txt` to any documentation page's URL to get its content as plain-text, LLM-optimized Markdown — the same text the `Copy Page` button copies.
+
+:::tip
+**Standard page**: [/docs/svelte-stores/debounceStore](/docs/svelte-stores/debounceStore)
+
+**LLM-friendly version**: [/docs/svelte-stores/debounceStore/llms.txt](/docs/svelte-stores/debounceStore/llms.txt)
+:::
+
+### Root index
+
+To explore every page in LLM-friendly format, visit the root index at [llms.txt](/llms.txt).
+
+### Complete documentation
+
+For a single, consolidated document containing all of the documentation, see [/docs/llms.txt](/docs/llms.txt).
+
+::
diff --git a/docs/src/content/guides/docs/authoring.md b/docs/src/content/guides/docs/authoring.md
@@ -0,0 +1,65 @@
+---
+title: Authoring content
+description: Directory layout, frontmatter, source inference, and examples.
+order: 3
+---
+
+Docs are plain markdown under `src/content/`, with live Svelte examples under
+`src/examples/`. Adding a page is usually just dropping in a `.md` file — the nav, table of
+contents, search index, and edit link all derive from it automatically.
+
+## Directory layout
+
+```
+src/content/
+  reference/<package>/<item>.md   # references collection (hand-authored)
+  guides/<name>.md                # guides — nest in subdirs to form categories
+src/examples/
+  components/<item>/<name>.svelte # referenced by :example{name="…"}
+```
+
+This page lives at `src/content/guides/docs/authoring.md` — the `docs/` subdirectory becomes
+the **Docs** category you see in the sidebar.
+
+## Frontmatter
+
+```md
+---
+title: SelectionState # required; becomes the page `name`
+description: Manage a set of selected items
+related: # cross-links (slug, or full URL)
+  - svelte-state/UniqueState
+order: 1 # optional manual sort within a group
+status: beta # optional badge (reference)
+hideTableOfContents: false
+---
+```
+
+Guides accept `title`, `description`, `category`, `order`, `draft`. References add `related`,
+`features`, `status`, `kind`, `sourceFile`, `hideUsage`, and more. Full schemas live in the
+framework's `content-collections` config.
+
+## Source-file inference (reference)
+
+A reference doc's source file is inferred from its path —
+`src/content/reference/<package>/<item>.md` → `<packagesRoot>/<package>/src/lib/<item>.{ts,svelte.ts}`
+(with a camelCase fallback: `Duration` → `duration.ts`, `SelectionState` →
+`selectionState.svelte.ts`). Add a `sourceFile:` frontmatter only to override.
+
+## Examples
+
+Reference a Svelte example from markdown with the `:example` directive:
+
+```md
+:example{name="basic" showCode}
+```
+
+The `name` resolves to `src/examples/components/<item>/<name>.svelte`. Supported props:
+`name`, `component`, `path`, `showCode`, `highlight` (e.g. `"7"` or `"7-9"`), and `class`.
+The example's `?raw` source powers both the show-code toggle and the inlined `llms.txt`
+output.
+
+:::note
+For all the markdown rendering features — callouts, tabs, steps, code highlighting, live
+code — see [Markdown & directives](/docs/guides/docs/markdown).
+:::
diff --git a/docs/src/content/guides/docs/cli.md b/docs/src/content/guides/docs/cli.md
@@ -0,0 +1,46 @@
+---
+title: CLI & generators
+description: Build-time generation for component docs via the layerstack-docs CLI.
+order: 5
+---
+
+`@layerstack/docs` ships a `layerstack-docs` binary with build-time generators. Hand-authored
+reference sites (like this one) don't need them; **generated** component-doc sites (like
+[LayerChart](https://layerchart.com)) use them to produce API tables, example catalogs,
+screenshots, StackBlitz bundles, and release notes.
+
+## Wiring
+
+Run cheap generators in `prebuild`; run heavy/committed artifacts (catalogs, screenshots)
+manually.
+
+```jsonc title="package.json"
+{
+  "scripts": {
+    "prebuild": "pnpm generate:api && pnpm generate:stackblitz && pnpm generate:releases",
+    "generate:api": "layerstack-docs generate-api ../packages/<pkg>/src/lib/components generated/api",
+    "generate:catalog": "layerstack-docs generate-catalog ../packages/<pkg>/src/lib/components src/examples/components src/examples/catalog",
+    "generate:screenshots": "layerstack-docs generate-screenshots src/examples/components static/screenshots",
+    "generate:stackblitz": "layerstack-docs generate-stackblitz src static/stackblitz-files.json [remote-sources.json]",
+    "generate:releases": "layerstack-docs generate-releases techniq/<repo> generated/releases",
+  },
+}
+```
+
+## Commands
+
+| Command                | Arguments                                                                                 | Generates                                                   |
+| ---------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
+| `generate-api`         | `<components-dir> <output-dir>`                                                           | Per-component prop API JSON (via the TypeScript compiler)   |
+| `generate-catalog`     | `<components-dir> <examples-dir> <catalog-dir>`                                           | Per-component example + cross-usage catalogs                |
+| `generate-screenshots` | `<examples-dir> <screenshots-dir> [--base-url] [--route-base] [--all]`                    | Responsive light/dark WebP screenshots (Playwright + sharp) |
+| `generate-stackblitz`  | `<source-dir> <output-file> [remote-sources-file] [--template-dir] [--source] [--remote]` | A StackBlitz/WebContainer file bundle                       |
+| `generate-releases`    | `<owner/repo> <output-dir>`                                                               | GitHub releases → frontmatter markdown files                |
+
+The output under `generated/api/*` and `generated/releases/*` is picked up automatically by
+the `references`/`components`/`releases` collections.
+
+:::note
+`generate-stackblitz` uses the package's bundled template at `templates/stackblitz-template`
+by default; pass `--template-dir` to override it.
+:::