Serve AI-Friendly Markdown Docs (llms.txt) from the Docs Site

.github/workflows/linting.yml

@@ -33,5 +33,7 @@ jobs:
         run: yarn build:css
       - name: Build Tokens
         run: yarn build:tokens
+      - name: Build LLMS Docs
+        run: yarn build-docs:llms
       - name: Build Storybook
-        run: yarn build-storybook
+        run: yarn build-docs:storybook

.github/workflows/publish-storybook.yml

@@ -24,12 +24,12 @@ jobs:
           yarn install --immutable
       - name: Build 🔧
         run: | # build the Storybook files
-          yarn build-storybook
+          yarn build-docs
       - name: Deploy 🚀
         uses: JamesIves/github-pages-deploy-action@3.6.2
         with:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           BRANCH: gh-pages # The branch the action should deploy to.
-          FOLDER: storybook-static # The folder that the build-storybook script generates files.
+          FOLDER: storybook-static # The folder that the build-docs:storybook script generates files.
           CLEAN: true # Automatically remove deleted files from the deploy branch
           TARGET_FOLDER: docs # The folder that we serve our Storybook files from

.gitignore

@@ -29,6 +29,7 @@ node_modules/
 
 # Distribution files
 dist
+llms-docs
 public/design-tokens.source.json
 
 *storybook.log

.prettierignore

@@ -2,3 +2,6 @@
 tools/templates
 .yarn/*
 optics-design-system.code-workspace
+
+# Generated docs
+llms-docs

.storybook/main.js

@@ -19,6 +19,12 @@ const config = {
       from: './assets',
       to: '/public',
     },
+    // AI-friendly markdown docs (llms.txt + per-page markdown), generated by
+    // `yarn build-docs:llms` which runs as part of the storybook scripts.
+    {
+      from: '../llms-docs',
+      to: '/',
+    },
   ],
 
   core: {

README.md

@@ -91,6 +91,18 @@ npm run generate
 
 The visual graphic found on the Selective Imports page in the documentation is generated from the `tools/generate-graph.dot` file. You can preview and export a newer svg version of the graphic by using the `tintinweb.graphviz-interactive-preview` VSCode extension.
 
+### AI-Friendly Documentation (llms.txt)
+
+[llms txt](https://llmstxt.org/)
+
+The docs site also serves the full documentation as plain markdown for AI tools:
+
+- [llms.txt](https://docs.optics.rolemodel.design/llms.txt) — index of every docs page
+- [llms-full.txt](https://docs.optics.rolemodel.design/llms-full.txt) — the entire documentation in one file
+- `https://docs.optics.rolemodel.design/llms/<page-slug>.md` — one markdown file per page
+
+These are generated from the Storybook MDX docs by `yarn build-docs:llms`. Each `<Canvas>` embed is replaced with the story's actual rendered HTML, and each token doc block with a table parsed from the token CSS.
+
 ## License
 
 [MIT](LICENSE)

package.json

@@ -11,15 +11,17 @@
     "build:css-min": "postcss 'src/optics*.css' -d dist/css --ext .min.css --env=minify",
     "build:tokens": "node build_token_json --source=src/core/tokens --output=dist/tokens/tokens.json",
     "build:files": "mkdir -p dist/css/addons; cp LICENSE README.md package.json dist/; cp -rL src/addons src/core src/components dist/css",
+    "build-docs": "yarn build-docs:llms && yarn build-docs:storybook",
+    "build-docs:llms": "node --disable-warning=MODULE_TYPELESS_PACKAGE_JSON tools/build-llms-docs.mjs",
+    "build-docs:storybook": "storybook build --docs",
     "storybook": "storybook dev -p 6006 --docs",
-    "build-storybook": "storybook build --docs",
     "lint": "yarn lint:js && yarn lint:css",
     "lint-fix": "yarn lint:js --fix && yarn lint:css --fix",
     "lint:js": "eslint 'src/stories/**/*.js'",
     "lint:css": "stylelint 'src/**/*.css'",
     "prettier": "prettier -w .",
     "prettier-check": "prettier -c .",
-    "sanity-check": "yarn lint && yarn prettier && yarn build && yarn build-storybook && rm -rf ./dist && rm -rf ./storybook-static",
+    "sanity-check": "yarn lint && yarn prettier && yarn build && yarn build-docs && rm -rf ./dist && rm -rf ./storybook-static && rm -rf ./llms-docs",
     "generate": "node ./tools/generate.js"
   },
   "repository": {
@@ -56,6 +58,7 @@
     "eslint-plugin-storybook": "^10.4.6",
     "generate-template-files": "^3.2.1",
     "globals": "^17.7.0",
+    "jsdom": "^29.1.1",
     "postcss": "^8.5.16",
     "postcss-cli": "^11.0.1",
     "postcss-import": "^16.1.1",