diff --git a/docs/README.md b/docs/README.md index b28211a9..436d7830 100644 --- a/docs/README.md +++ b/docs/README.md @@ -39,3 +39,39 @@ GIT_USER= 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 and 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
and 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. \ No newline at end of file diff --git a/docs/package.json b/docs/package.json index 095e3479..21b47600 100644 --- a/docs/package.json +++ b/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", diff --git a/docs/pdf/openrag-documentation.pdf b/docs/pdf/openrag-documentation.pdf deleted file mode 100644 index 8009577b..00000000 Binary files a/docs/pdf/openrag-documentation.pdf and /dev/null differ diff --git a/docs/scraper.config.json b/docs/scraper.config.json index 94c57806..8a3d3daf 100644 --- a/docs/scraper.config.json +++ b/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 } \ No newline at end of file diff --git a/documents/openrag-documentation.pdf b/documents/openrag-documentation.pdf index cec6d2aa..48a06f72 100644 Binary files a/documents/openrag-documentation.pdf and b/documents/openrag-documentation.pdf differ