docs: add descriptions to docs pages and improve LLM support in build script (#935)

vonovak · web-flow · commit 67890f632cd6 · 2026-02-27T19:34:28.000+01:00
- Added meaningful descriptions to documentation pages for better readability.
- Enhanced the LLM output by stripping unnecessary syntax in the post-build clean-up script.
- Updated the build script to automatically execute post-build cleanup.
diff --git a/docs/docs/install.mdx b/docs/docs/install.mdx
@@ -1,6 +1,7 @@
 ---
 sidebar_position: 1
 sidebar_label: Installation & Setup
+description: Installation and setup guide for @react-native-documents/picker and @react-native-documents/viewer with Expo and bare React Native
 ---
 
 # Installation
diff --git a/docs/docs/sponsor-only/errors.md b/docs/docs/sponsor-only/errors.md
@@ -1,5 +1,6 @@
 ---
 sidebar_position: 60
+description: Error handling guide covering error codes, isErrorWithCode helper, and best practices for document picker and viewer
 ---
 
 # Error handling
diff --git a/docs/docs/sponsor-only/intro.md b/docs/docs/sponsor-only/intro.md
@@ -1,5 +1,6 @@
 ---
 sidebar_position: 0
+description: Introduction to @react-native-documents/picker and @react-native-documents/viewer packages for picking, saving, and viewing documents in React Native
 ---
 
 # Introduction
diff --git a/docs/docs/sponsor-only/jest-mocks.md b/docs/docs/sponsor-only/jest-mocks.md
@@ -1,5 +1,6 @@
 ---
 sidebar_position: 50
+description: Jest module mocks for testing with @react-native-documents/picker and @react-native-documents/viewer
 ---
 
 # Jest module mocks
diff --git a/docs/docs/sponsor-only/license.md b/docs/docs/sponsor-only/license.md
@@ -1,6 +1,7 @@
 ---
 sidebar_position: 80
 sidebar_label: License
+description: MIT license for the document picker and viewer packages
 ---
 
 # License
diff --git a/docs/docs/sponsor-only/migration.md b/docs/docs/sponsor-only/migration.md
@@ -1,5 +1,6 @@
 ---
 sidebar_position: 2
+description: Migration guide from react-native-document-picker to @react-native-documents/picker with step-by-step instructions
 ---
 
 # Migrating from the old document-picker
diff --git a/docs/docs/sponsor-only/picker/directory-picker.mdx b/docs/docs/sponsor-only/picker/directory-picker.mdx
@@ -1,5 +1,6 @@
 ---
 sidebar_position: 6
+description: Pick a directory from the file system with optional long-term access for persistent file I/O
 ---
 
 # Directory picker
diff --git a/docs/docs/sponsor-only/picker/integrating-on-android.mdx b/docs/docs/sponsor-only/picker/integrating-on-android.mdx
@@ -1,5 +1,6 @@
 ---
 sidebar_position: 10
+description: Android-specific usage notes comparing Open and Import modes with screenshots
 ---
 
 # Android usage notes
diff --git a/docs/docs/sponsor-only/picker/keeping-local-copy.mdx b/docs/docs/sponsor-only/picker/keeping-local-copy.mdx
@@ -1,6 +1,7 @@
 ---
 sidebar_position: 4
 sidebar_label: Keeping a local file copy
+description: Use keepLocalCopy to save picked files to your app's storage on Android and iOS
 ---
 
 # Keeping a local copy of the picked files {#keepLocalCopy}
diff --git a/docs/docs/sponsor-only/picker/save-as-dialog.mdx b/docs/docs/sponsor-only/picker/save-as-dialog.mdx
@@ -1,6 +1,7 @@
 ---
 sidebar_position: 0
 sidebar_label: Save As dialog
+description: Present a Save As dialog using saveDocuments to let users save files to a location of their choice
 ---
 
 # 'Save As' dialog
diff --git a/docs/docs/sponsor-only/picker/virtual-files.md b/docs/docs/sponsor-only/picker/virtual-files.md
@@ -1,3 +1,7 @@
+---
+description: Handle Android virtual files (Google Docs, Sheets) in the document picker with allowVirtualFiles
+---
+
 # Virtual files
 
 Virtual files are an Android-only concept. You have almost surely encountered them in your Google Drive - all the Google Docs, Sheets, Presentations, etc. are virtual files and cannot normally be selected.
diff --git a/docs/docs/sponsor-only/viewer.mdx b/docs/docs/sponsor-only/viewer.mdx
@@ -1,6 +1,7 @@
 ---
 sidebar_position: 30
 sidebar_class_name: larger-heading
+description: Document viewer for previewing files by uri or bookmark on Android (Intent.ACTION_VIEW) and iOS (QuickLook)
 ---
 
 # Document Viewer
diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts
@@ -74,10 +74,32 @@ const config: Config = {
     [
       'docusaurus-plugin-llms',
       {
-        // Enable both content cleaning options for optimal LLM output
-        ignoreFiles: ['license**', 'other-libs**'],
+        ignoreFiles: ['license*', 'other-libs*'],
         fullContent: true,
+        excludeImports: false,
         removeDuplicateHeadings: true,
+        description:
+          'Document picker and viewer for React Native and Expo apps (Android, iOS). Packages: @react-native-documents/picker, @react-native-documents/viewer',
+        rootContent: `## Overview\n\n\`@react-native-documents/picker\` lets users pick, import, or save documents from the device's file system. \`@react-native-documents/viewer\` previews documents using native viewers (QuickLook on iOS, Intent.ACTION_VIEW on Android).\n\nKey features:\n- **Import mode**: pick a file and keep your own copy\n- **Open mode**: access the selected document directly, with optional long-term permissions\n- **Save As dialog**: let users save files to a location of their choice\n- **Directory picker**: pick a directory for file I/O operations\n- **Document viewer**: preview files by uri or bookmark\n\n## Quick start\n\n1. Install the package (see Installation & Setup)\n2. Use \`pick()\` to let users select documents\n3. Optionally use \`keepLocalCopy()\` to save files to your app's storage\n4. Use \`viewDocument()\` from the viewer package to preview files\n\n## Docs`,
+        fullRootContent: `## Overview\n\n\`@react-native-documents/picker\` lets users pick, import, or save documents from the device's file system. \`@react-native-documents/viewer\` previews documents using native viewers (QuickLook on iOS, Intent.ACTION_VIEW on Android).\n\nKey features:\n- **Import mode**: pick a file and keep your own copy of it\n- **Open mode**: access the selected document directly, with optional long-term access permissions that persist across app restarts\n- **Save As dialog**: present \`saveDocuments()\` to let users save files to a location of their choice\n- **Directory picker**: pick a directory for file I/O with optional long-term access\n- **Virtual files**: handle Android virtual files (Google Docs, Sheets) via \`allowVirtualFiles\`\n- **Document viewer**: preview files by uri or bookmark using \`viewDocument()\`\n- **keepLocalCopy**: separate file picking from copying, making your app more responsive\n\nKey patterns:\n- Use \`pick()\` to present the document picker, destructure the result: \`const [result] = await pick()\`\n- Handle errors with \`isErrorWithCode()\` helper and \`errorCodes\` object\n- Use \`keepLocalCopy()\` after picking to save to app storage (replaces the old \`copyTo\` option)\n- Use \`requestLongTermAccess\` for persistent file access across app restarts`,
+        includeOrder: [
+          'install*',
+          'intro*',
+          '**/picker/import-mode*',
+          '**/picker/open-mode*',
+          '**/picker/save-as-dialog*',
+          '**/picker/keeping-local-copy*',
+          '**/picker/limiting-selectable-files*',
+          '**/picker/directory-picker*',
+          '**/picker/virtual-files*',
+          '**/picker/integrating-on-android*',
+          '**/viewer*',
+          'errors*',
+          'jest-mocks*',
+          'migration*',
+          'doc-picker-api/**',
+          'doc-viewer-api/**',
+        ],
       },
     ],
     ...(process.env.ENABLE_DOC_GEN === 'true'
diff --git a/docs/package.json b/docs/package.json
@@ -4,7 +4,7 @@
   "private": true,
   "scripts": {
     "start": "ENABLE_DOC_GEN=true docusaurus start",
-    "build": "docusaurus build",
+    "build": "docusaurus build && node scripts/clean-llm-files.mjs",
     "swizzle": "docusaurus swizzle",
     "deploy": "docusaurus deploy",
     "clear": "docusaurus clear",
diff --git a/docs/scripts/clean-llm-files.mjs b/docs/scripts/clean-llm-files.mjs
@@ -0,0 +1,103 @@
+/**
+ * Post-build cleanup for LLM documentation files.
+ * Strips Docusaurus-specific syntax (JSX components, admonitions, etc.)
+ * that isn't useful for LLM consumption.
+ *
+ * Usage: node scripts/clean-llm-files.mjs
+ */
+
+import { readFileSync, writeFileSync } from 'fs'
+import { join } from 'path'
+
+const BUILD_DIR = join(import.meta.dirname, '..', 'build')
+const FILES = ['llms.txt', 'llms-full.txt']
+
+/**
+ * Cleanups safe to apply everywhere (including inside code blocks).
+ */
+function cleanGlobal(content) {
+  return (
+    content
+      // Remove Docusaurus code block attributes (showLineNumbers, title)
+      .replace(
+        /^(```\w*)\s+(?:title="[^"]*"\s*)?(?:showLineNumbers\s*)?$/gm,
+        '$1',
+      )
+      // Collapse 3+ consecutive blank lines to 2
+      .replace(/\n{4,}/g, '\n\n\n')
+  )
+}
+
+/**
+ * Cleanups that must ONLY apply outside of fenced code blocks
+ * to avoid mangling code examples.
+ */
+function cleanProse(text) {
+  return (
+    text
+      // Remove Docusaurus theme imports
+      .replace(/^import .+ from '@theme\/.*';\n?/gm, '')
+      // Convert <TabItem label="..."> to a bold label, remove other Tabs markup
+      .replace(/<\/?Tabs[^>]*>\n?/g, '')
+      .replace(/<TabItem[^>]*label="([^"]*)"[^>]*>\n?/g, '**$1:**\n')
+      .replace(/<TabItem[^>]*>\n?/g, '')
+      .replace(/<\/TabItem>\n?/g, '')
+      // Remove <details>/<summary> (keep inner content)
+      .replace(/<details>\n?/g, '')
+      .replace(/<\/details>\n?/g, '')
+      .replace(/<summary>(.*?)<\/summary>\n?/g, '**$1**\n')
+      // Convert admonitions to blockquote labels
+      .replace(
+        /^:::(tip|warning|note|danger|important|info)\n?/gm,
+        (_, type) =>
+          `> **${type.charAt(0).toUpperCase() + type.slice(1)}**: `,
+      )
+      .replace(/^:::\n?/gm, '\n')
+      // Remove highlight markers
+      .replace(/^\s*\/\/ highlight-(?:start|end|next-line)\n?/gm, '')
+      // Remove markdown comments
+      .replace(/^\[\/\/\]: # '.*?'\n?/gm, '')
+      // Remove image references (local paths, not useful for LLMs)
+      .replace(/^[ \t]*!\[.*?\]\(\/img\/.*?\)\n?/gm, '')
+      // Remove inline img tags with local paths
+      .replace(/^.*<img\s+src=\{?['"]\/img\/[^}]*\}?\s*[^>]*\/>\s*\n?/gm, '')
+      // Clean up JSX expressions like {'>='} to just the text
+      .replace(/\{'\s*(.*?)\s*'\}/g, '$1')
+  )
+}
+
+/**
+ * Split content into code-fenced and non-code-fenced segments,
+ * apply prose cleanup only to non-code segments, then reassemble.
+ */
+function cleanContent(content) {
+  const parts = content.split(/^(```\w*.*$)/gm)
+  let insideCodeBlock = false
+  const cleaned = parts.map((part) => {
+    if (/^```\w*/.test(part)) {
+      insideCodeBlock = !insideCodeBlock
+      return part
+    }
+    return insideCodeBlock ? part : cleanProse(part)
+  })
+
+  return cleanGlobal(cleaned.join(''))
+}
+
+for (const file of FILES) {
+  const filePath = join(BUILD_DIR, file)
+  try {
+    const content = readFileSync(filePath, 'utf-8')
+    const cleaned = cleanContent(content)
+    writeFileSync(filePath, cleaned)
+    const reduction = (
+      ((content.length - cleaned.length) / content.length) *
+      100
+    ).toFixed(1)
+    console.log(
+      `Cleaned ${file}: ${content.length} -> ${cleaned.length} bytes (${reduction}% reduction)`,
+    )
+  } catch (err) {
+    console.error(`Error processing ${file}:`, err.message)
+  }
+}
