docs: build PDF to /documents directory (#335)

* move-pdf-output-dir-to-documents-pdf

* add-readme

* Apply suggestion from @mendonk

* Apply suggestion from @aimurphy

Co-authored-by: April I. Murphy <36110273+aimurphy@users.noreply.github.com>

* Apply suggestion from @aimurphy

Co-authored-by: April I. Murphy <36110273+aimurphy@users.noreply.github.com>

---------

Co-authored-by: April I. Murphy <36110273+aimurphy@users.noreply.github.com>

docs/README.md

@@ -39,3 +39,39 @@ GIT_USER=<Your GitHub username> yarn deploy
 ```
 
 If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
+
+## Update the OpenRAG documentation PDF
+
+The documentation PDF at `openrag/documents/openrag-documentation.pdf` is used by the OpenRAG application, so keep it up to date.
+
+To update the PDF, do the following:
+
+1. Remove elements from the `docs/*.mdx` files.
+Content in tabs, details, and summary elements is hidden from PDF builds and it must be included.
+To remove these items, give the following prompt or something similar to your IDE.
+
+   ```
+   Flatten documentation for PDF: remove tabs and details elements
+   In all MDX files in docs/docs/, flatten interactive elements:
+   Remove all <Tabs> and <TabItem> components:
+   Convert each tab's content to a regular section with an appropriate heading (### for subsections, ## for main sections)
+   Show all tab content sequentially
+   Remove the import statements for Tabs and TabItem where they're no longer used
+   Remove all <details> and <summary> elements:
+   Convert details content to regular text with an appropriate heading (### for subsections)
+   Show all content directly (no collapsible sections)
+   Keep all content visible — nothing should be hidden or collapsed
+   Maintain proper formatting and structure
+   Apply this to all documentation files that contain tabs or details elements so the content is fully flat and visible for PDF generation.
+   ```
+
+2. Check your `.mdx` files to confirm these elements are removed.
+Don't commit the changes.
+
+3. From `openrag/docs`, run this command to build the site with the changes, and create a PDF at `openrag/documents`.
+
+   ```
+   npm run build:pdf
+   ```
+
+4. Check the PDF's content, then commit and create a pull request.

docs/package.json

@@ -6,7 +6,7 @@
     "docusaurus": "docusaurus",
     "start": "docusaurus start",
     "build": "docusaurus build",
-    "build:pdf": "npm run build && npm run serve & sleep 10 && npx docusaurus-to-pdf && pkill -f 'docusaurus serve'",
+    "build:pdf": "rm -f ../documents/openrag-documentation.pdf && npm run build && npm run serve & sleep 10 && npx docusaurus-to-pdf && pkill -f 'docusaurus serve'",
     "swizzle": "docusaurus swizzle",
     "deploy": "docusaurus deploy",
     "clear": "docusaurus clear",

docs/scraper.config.json

@@ -1,7 +1,7 @@
 {
   "baseUrl": "http://localhost:3000",
   "entryPoint": "http://localhost:3000",
-  "outputDir": "./pdf/openrag-documentation.pdf",
+  "outputDir": "../documents/openrag-documentation.pdf",
   "customStyles": "table { max-width: 3500px !important; } .navbar, .footer, .breadcrumbs { display: none !important; }",
   "forceImages": true
 }