feat: adopt @signalwire/docusaurus-plugin-llms-txt (Phase 1)

.github/workflows/deploy.yaml

@@ -61,6 +61,34 @@ jobs:
           echo "Using DOCUSAURUS_URL: $DOCUSAURUS_URL"
           npm run build || (echo "Site build failed" && exit 1)
 
+      - name: Verify flat-markdown export
+        run: |
+          # @signalwire/docusaurus-plugin-llms-txt should have produced one
+          # .md file per HTML page plus an llms.txt index. This artifact is
+          # consumed by @harperfast/skills (and any third-party LLM tooling).
+          # Fail the build loudly if it didn't run or produced no output.
+          set -euo pipefail
+          failures=0
+          for dir in learn reference fabric release-notes; do
+            count=$(find "build/$dir" -name '*.md' 2>/dev/null | wc -l | tr -d ' ')
+            if [ "$count" -lt 1 ]; then
+              echo "::error::No .md files generated under build/$dir/ — llms-txt plugin failed for this docs instance"
+              failures=$((failures + 1))
+            else
+              echo "build/$dir: $count .md files"
+            fi
+          done
+          for f in build/llms.txt build/llms-full.txt; do
+            if [ ! -f "$f" ]; then
+              echo "::error::Expected artifact $f is missing"
+              failures=$((failures + 1))
+            fi
+          done
+          if [ "$failures" -gt 0 ]; then
+            exit 1
+          fi
+          echo "✓ Flat-markdown export verified"
+
       - name: Upload npm logs on failure
         if: failure()
         uses: actions/upload-artifact@v6

docusaurus.config.ts

@@ -211,6 +211,42 @@ const config: Config = {
 					],
 				]
 			: []),
+
+		// LLM-friendly flat markdown export.
+		//
+		// Generates a per-page .md file alongside each HTML page (mirroring
+		// the route structure under build/) plus an llms.txt index. The
+		// markdown output is consumed by @harperfast/skills for rule
+		// generation and is also a public artifact for any third-party LLM
+		// tooling that wants to ingest our docs.
+		//
+		// The plugin runs in postBuild against rendered HTML, so multi-
+		// instance docs plugin output (learn, reference, fabric,
+		// release-notes) is captured uniformly without per-instance
+		// configuration. MDX components, theme components, and build-time
+		// data are all already resolved by the time it runs.
+		//
+		// No excludeRoutes: we emit flat markdown for the full site,
+		// including v4 reference docs. Consumers (e.g. the skills repo
+		// manifest) decide which routes to actually use.
+		[
+			'@signalwire/docusaurus-plugin-llms-txt',
+			{
+				content: {
+					// Defaults: enableMarkdownFiles: true, includeDocs: true,
+					// includeVersionedDocs: true. All four docs plugin instances
+					// (learn, reference, fabric, release-notes) are picked up
+					// automatically; v4 reference docs are included so the public
+					// artifacts cover the full site.
+					enableLlmsFullTxt: true,
+					// Run our Docusaurus-aware cleanup transforms before the
+					// plugin's default rehype pipeline so the HTML→Markdown
+					// conversion sees clean structure. See the script header
+					// for details on what gets transformed.
+					beforeDefaultRehypePlugins: [require('./scripts/rehype-docusaurus-to-llms.mjs').default],
+				},
+			},
+		],
 	],
 
 	themes: [