feat: Community App Guides section and Paperless NGX placeholder#407
Open
grizzlechips wants to merge 36 commits intounraid:mainfrom
Open
feat: Community App Guides section and Paperless NGX placeholder#407grizzlechips wants to merge 36 commits intounraid:mainfrom
grizzlechips wants to merge 36 commits intounraid:mainfrom
Conversation
… notification icons - Expand notification settings documentation with detailed configuration options: * Add comprehensive display/behavior settings, notification types, and delivery methods * Include step-by-step SMTP configuration with Gmail app password setup * Add detailed notification agent setup with icons for 13+ services (Discord, Slack, Telegram, etc.) - Significantly expand VM setup documentation with new Unraid 7.x features: * Add comprehensive VM snapshot management (create, revert, block commit/pull) * Include detailed troubleshooting sections and storage considerations * Expand GPU passthrough and PCI device binding documentation - Enhance system administration guides with detailed upgrade/downgrade procedures: * Add a comprehensive downgrade process via the Downgrade OS tool * Include post-downgrade verification and troubleshooting sections * Add warnings about ZFS compatibility and plugin issues - Add Creative Commons license information to the footer configuration - Include 20+ notification service icons (Discord, Slack, Telegram, Pushover, etc.) - Update Docker guide image and other visual assets
- Clarify WebGUI downgrade tool scope in upgrading-unraid.mdx - Fix broken snapshot link and list formatting in vm-setup.mdx - Correct Parity 2 technical description (Reed-Solomon Q-parity) in array-configuration.mdx - Fix compound adjective hyphenation (XFS‑formatted) - Remove redundant wording and incorrect "Sync" button reference in rebuild steps - Standardize formatting and cross-references in tailscale.mdx
Correct inaccurate "Memory dump" checkbox description - it's not preselected by default. Replace alarmist "permanent crash state" language with accurate explanation of memory-backed vs disk-only snapshots and their trade-offs.
- Fix inconsistent vDisk storage paths in VM conversion docs (use /mnt/user/ instead of /mnt/cache/) - Correct IDE vs SATA bus guidance to change both bus and dev attributes - Replace Force stop recommendation with safer Stop/normal shutdown guidance - Organize notification agent icons in dedicated static directory structure - Fix incorrect rebuild instruction (change "Sync" to "Start" button guidance)
Address critical feedback about content hidden behind tabbed/collapsible elements by reorganizing content as inline sections while maintaining clean layouts. **FAQ & Licensing FAQ:** - Improve anchor linking with heading structure (unique shareable links without cluttering TOC) - Flatten all questions for immediate accessibility - Verify all anchors work correctly **Array Configuration:** - Split monolithic 1,160+ line page into 5 focused pages: Overview, Adding disks, Replacing disks, Removing disks, Health & maintenance - Flatten content from tabs/expandables to inline sections - Retain version-specific tabs only - Update links and redirects for new structure **File Systems:** - Add Unraid 7.2 filesystem content (EXT4, NTFS, exFAT) - Add filesystem comparison table at top of page - Remove tab UI for filesystem introductions - Retain CLI-specific tabs for file system checks/repairs - Consolidate redundant partial files (btrfs/xfs/zfs intro, balance/scrub partials) - Add cross-reference link to ZFS storage page **Shares:** - Convert configurable option tabs to inline sections with descriptive headers - Move "Transferring files from network share" to CLI page (per feedback) - Retain version-specific tabs for 6.12+ vs 6.11 differences - Update links for new content location **Cache Pools:** - Remove tab UI, convert to inline sections - Delete "Backing up cache pool" section (redundant with move operations, per feedback) - Retain version-specific guidance as inline notes - Improve content flow with clear section headers **Unclean Shutdowns:** - Flatten tabbed VM configuration to inline sections - Expand Windows VM configuration with detailed step-by-step instructions - Add comprehensive timeout configuration tables - Enhance shutdown sequence explanations **Additional improvements:** - Improve CLI documentation with network file transfer section - Enhance VM setup documentation accessibility - Update Apple Time Machine style/formatting - Add ZFS storage cross-references - Apply CodeRabbit configuration file improvements - Reduce excessive bold text across pages for better visual hierarchy (maintain content substance)
- Changed import path for sidebar sorting utility from `sitebar-semver-sort.js` to `sidebar-semver-sort.js`. - Removed outdated `sitebar-semver-sort` TypeScript definition and JavaScript implementation. - Updated various documentation files for consistency, including fixing minor grammatical issues and improving formatting for better readability. - Adjusted links in the Docusaurus configuration to point to the new overview page for managing storage arrays.
- Changed the maximum heading level for the table of contents from 2 to 3 to improve navigation. - Removed the outdated index section to streamline the FAQ content and enhance readability.
…bility - Changed table of contents maximum heading level from 2 to 3 for better organization. - Removed outdated index sections from the FAQ to streamline content and enhance user experience. - Improved overall clarity and accessibility of the FAQ and Licensing FAQ sections.
- Removed outdated redirect entries in docusaurus.config.ts for clarity. - Enhanced API documentation with consistent formatting and improved readability across multiple files. - Updated CLI and API key management guides to reflect best practices and streamline user experience. - Improved overall structure and accessibility of various documentation sections, including OIDC provider setup and array management. - Minor editorial fixes and adjustments to ensure consistency in terminology and formatting.
- Updated redirect paths in docusaurus.config.ts to point to the new overview page for array management. - Improved API documentation formatting and consistency across multiple files. - Adjusted image paths in ZFS storage documentation to reference the correct assets folder. - Added markdown linting comments for better formatting in various Docker container management guides. - Removed outdated images related to ZFS storage to clean up the repository.
- Adjusted image paths in the ZFS storage documentation across multiple languages to reference the correct assets folder. - Ensured consistency in image references for better accessibility and organization of documentation.
- Corrected formatting of the eMMC support section in the release notes. - Ensured consistent use of backslashes in configuration options for clarity.
- Changed the tagline in docusaurus.config.ts for clarity. - Updated favicon path to use .ico format. - Ensured consistent use of backslashes in release notes for package versions.
- Standardized section headings for consistency across various settings pages. - Added detailed instructions for WiFi setup, including initial requirements and limitations. - Enhanced RAIDZ expansion documentation with step-by-step guidance and important notes. - Clarified BTRFS and ZFS pool management instructions, including adding disks and changing RAID levels. - Improved formatting and readability throughout the documentation for better user experience.
- Replaced outdated image reference in the ZFS storage documentation with a new image for improved clarity and accuracy.
- Updated Node.js version in .nvmrc to 24.11.1 for compatibility. - Added 'i18n/' to .remarkignore to exclude internationalization files from linting. - Integrated remarkComment plugin into .remarkrc.mjs for enhanced comment handling. - Adjusted docusaurus.config.ts to include markdown hooks for broken link warnings. - Updated package dependencies to latest versions for improved performance and security. - Fixed sidebar sorting logic to sort items in descending order. - Updated GitHub Actions workflows to use the latest setup-node action and improved error handling for linting. - Enhanced various documentation files for clarity, including API usage, licensing FAQs, and troubleshooting guides. - Removed outdated references and improved formatting across multiple language files.
…mentation - Moved markdown hooks under customFields in docusaurus.config.ts for better organization. - Revised the licensing FAQ to clarify installation methods for license key files, including detailed steps for WebGUI, network share, and USB flash drive installations, enhancing user guidance and accessibility.
- Moved markdown hooks directly under the markdown key for improved clarity and organization, removing the unnecessary customFields wrapper.
- Updated the markdown configuration to include hooks for handling broken markdown links, enhancing the clarity and functionality of the setup.
- Add guides plugin and navbar link (Community App Guides) - Improve guides intro content and link to docs repo - Add dummy page for Paperless NGX for client preview Co-authored-by: Cursor <cursoragent@cursor.com>
Contributor
📝 WalkthroughWalkthroughAdds a new "Community App Guides" section: a guides plugin and sidebar, two guide pages, a locale-aware Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Poem
🚥 Pre-merge checks | ✅ 1 | ❌ 2❌ Failed checks (1 warning, 1 inconclusive)
✅ Passed checks (1 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
|
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
docusaurus.config.ts (1)
269-278: Consider addingremarkAutoGlossaryto the guides pluginThe guides plugin omits all
remarkPlugins, so glossary terms in guide content won't be auto-linked, breaking visual consistency with the main docs. If that's intentional (e.g., community guides skip strict linting), it's worth documenting. Otherwise, adding at minimumremarkAutoGlossarykeeps glossary behaviour uniform:♻️ Proposed addition
[ "@docusaurus/plugin-content-docs", { id: "guides", path: "guides", routeBasePath: "guides", sidebarPath: "./sidebarsGuides.js", editUrl: createEditUrl, + remarkPlugins: [ + [remarkAutoGlossary, { yamlFile: "glossary.yaml" }], + ], }, ],🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docusaurus.config.ts` around lines 269 - 278, The guides docs plugin block (the array with id "guides" in docusaurus.config.ts) currently omits remarkPlugins so glossary terms won't be auto-linked; either add remarkAutoGlossary into that plugin's remarkPlugins array (e.g., inside the same config object where id: "guides", path: "guides", routeBasePath: "guides", sidebarPath, editUrl are defined) to enable consistent auto-linking with main docs, or add a short comment/documentation on the plugin config explaining the omission is intentional.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docusaurus.config.ts`:
- Around line 32-46: The createEditUrl function currently returns string; change
its return type to string | undefined and update its logic so that when locale
!== DEFAULT_LOCALE and versionDocsDirPath === "guides" (or otherwise identifying
guides pages) it returns undefined to suppress the edit link for
non-default-locale guides; keep existing behavior for other docs (return
translate URL for non-default locale when not guides, and the GitHub edit URL
using branch/process.env.GITHUB_BRANCH, versionDocsDirPath, docPath for default
locale).
---
Nitpick comments:
In `@docusaurus.config.ts`:
- Around line 269-278: The guides docs plugin block (the array with id "guides"
in docusaurus.config.ts) currently omits remarkPlugins so glossary terms won't
be auto-linked; either add remarkAutoGlossary into that plugin's remarkPlugins
array (e.g., inside the same config object where id: "guides", path: "guides",
routeBasePath: "guides", sidebarPath, editUrl are defined) to enable consistent
auto-linking with main docs, or add a short comment/documentation on the plugin
config explaining the omission is intentional.
ℹ️ Review info
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
docusaurus.config.ts
Comment on lines
+32
to
+46
| function createEditUrl({ | ||
| locale, | ||
| versionDocsDirPath, | ||
| docPath, | ||
| }: { | ||
| locale: string; | ||
| versionDocsDirPath: string; | ||
| docPath: string; | ||
| }): string { | ||
| if (locale !== DEFAULT_LOCALE) { | ||
| return `https://translate.unraid.net/unraid-docs/${locale}`; | ||
| } | ||
| const branch = process.env.GITHUB_BRANCH || "main"; | ||
| return `https://github.com/unraid/docs/edit/${branch}/${versionDocsDirPath}/${docPath}`; | ||
| } |
Contributor
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, let's examine the docusaurus.config.ts file to see the actual code
head -350 docusaurus.config.ts | tail -320Repository: unraid/docs
Length of output: 10987
🏁 Script executed:
# Let's also check the exact content around the lines mentioned
cat -n docusaurus.config.ts | sed -n '30,50p'Repository: unraid/docs
Length of output: 720
🏁 Script executed:
# Check the guides plugin definition around line 269-278
cat -n docusaurus.config.ts | sed -n '260,290p'Repository: unraid/docs
Length of output: 1107
🏁 Script executed:
# Let's search for where createEditUrl is used
rg "createEditUrl" docusaurus.config.ts -nRepository: unraid/docs
Length of output: 155
🌐 Web query:
Docusaurus v3.9.2 EditUrlFunction type signature return value
💡 Result:
In Docusaurus v3.9.2, EditUrlFunction is typed to return either a string edit URL or undefined (to disable the edit link for that specific doc):
type EditUrlFunction = (params: {
version: string;
versionDocsDirPath: string;
docPath: string;
permalink: string;
locale: string;
}) => string | undefined;[1]
createEditUrl return type prevents suppressing edit links for guides in non-default locales
Docusaurus v3.9.2's EditUrlFunction signature returns string | undefined — returning undefined suppresses the "Edit this page" button entirely. The current return type string prevents this.
Since createEditUrl is shared by both the main docs preset and the guides plugin, every non-default-locale page in /guides/ will show an edit link pointing to https://translate.unraid.net/unraid-docs/${locale} — a page unrelated to community guides if they aren't on the translation platform.
Change the return type to string | undefined and return undefined for the guides plugin in non-default locales (or conditionally based on versionDocsDirPath === "guides").
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docusaurus.config.ts` around lines 32 - 46, The createEditUrl function
currently returns string; change its return type to string | undefined and
update its logic so that when locale !== DEFAULT_LOCALE and versionDocsDirPath
=== "guides" (or otherwise identifying guides pages) it returns undefined to
suppress the edit link for non-default-locale guides; keep existing behavior for
other docs (return translate URL for non-default locale when not guides, and the
GitHub edit URL using branch/process.env.GITHUB_BRANCH, versionDocsDirPath,
docPath for default locale).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a dedicated Community App Guides section (building on the approach from PR #405) and a placeholder guide for Paperless NGX so the client can preview how guides look in context.
What's included
Community App Guides section
/guides/) and are clearly separate from core Unraid documentation./guides/.guides/intro.mdx) describing the section, "Last validated" expectations, and link to the main docs repo for contribution guidelines.sidebarsGuides.js.Paperless NGX dummy page
guides/paperless-ngx.mdxwith a "Last validated" block and short intro, to demonstrate how a real guide will appear in the section.Summary by CodeRabbit
New Features
Documentation
Chores