docs: Flatten tabbed content and improve documentation accessibility #368
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)
📝 WalkthroughWalkthroughModularized array documentation into a new Changes
Sequence Diagram(s)sequenceDiagram
participant Browser
participant Server as Doc Server
participant Router as Redirects
participant Parser as Remark/MDX
Browser->>Server: Request URL
Server->>Router: Lookup redirect map
alt Redirect found
Router->>Browser: 301 -> New URL
Browser->>Server: Request New URL
end
Server->>Parser: Load & parse MDX (remark plugins: directives, mdx)
Parser-->>Server: Rendered HTML (inline headings/components)
Server->>Browser: Serve rendered page
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Areas to focus review on:
Poem
Pre-merge checks and finishing touches❌ Failed checks (2 warnings)
✅ Passed checks (1 passed)
✨ 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}
There was a problem hiding this comment.
Actionable comments posted: 5
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/unraid-os/using-unraid-to/manage-storage/apple-time-machine.mdx (1)
6-7: Remove unused Tabs and TabItem imports.Lines 6–7 import
TabsandTabItemfrom@theme/Tabs, but neither component is used anywhere in the file. Given the PR objective to "flatten tabbed content and improve documentation accessibility," these imports should be removed.Apply this diff:
-import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -
🧹 Nitpick comments (6)
docs/unraid-os/troubleshooting/licensing-faq.mdx (1)
87-87: Minor: Inconsistent quote style in inline JSX styles.Lines 87 and 119/198 use different quote conventions for CSS property values within
styleobjects. Line 87 uses double quotes (display: "flex"), while lines 119 and 198 use single quotes (display: 'flex'). Consider standardizing across all inline styles for consistency.Apply this diff to standardize quote usage:
- <div style={{ display: 'flex', justifyContent: 'center', margin: '20px 0' }}> + <div style={{ display: "flex", justifyContent: "center", margin: "20px 0" }}>Also applies to: 119-119, 198-198
docs/unraid-os/troubleshooting/common-issues/unclean-shutdowns.mdx (1)
303-309: Consolidate repeated Dynamix Stop Shell links.The same Dynamix Stop Shell link appears multiple times in this section (lines 303, 308-309). Consider extracting this as a reference variable or shortening repetition for maintainability.
+[Dynamix Stop Shell plugin](https://unraid.net/community/apps/c/tools-system/p2?srsltid=AfmBOoqBXyDNfHxRDCL7Fv9Gcfz8-8CdHmiJSX16PRZpZLLzgQtw2mVk) **Dynamix Stop Shell plugin:** -If you frequently use SSH or terminal sessions, open sessions can prevent clean shutdowns because Unraid waits for them to close before proceeding. +If you frequently use SSH or terminal sessions, open sessions can prevent clean shutdowns because Unraid waits for them to close before proceeding. -The [Dynamix Stop Shell](https://unraid.net/community/apps/c/tools-system/p2?srsltid=AfmBOoqBXyDNfHxRDCL7Fv9Gcfz8-8CdHmiJSX16PRZpZLLzgQtw2mVk#:~:text=the%20given%20interval.-,Dynamix%20Stop%20Shell,-Dynamix%20Repository) plugin helps by automatically closing lingering bash or SSH sessions when the array is stopped, ensuring a timely shutdown. +The [Dynamix Stop Shell plugin] helps by automatically closing lingering bash or SSH sessions when the array is stopped, ensuring a timely shutdown. -You can install it from [Community Applications (search for "Dynamix Stop Shell")](https://unraid.net/community/apps/c/tools-system/p2?srsltid=AfmBOoqBXyDNfHxRDCL7Fv9Gcfz8-8CdHmiJSX16PRZpZLLzgQtw2mVk#:~:text=the%20given%20interval.-,Dynamix%20Stop%20Shell,-Dynamix%20Repository). +You can install it from [Community Applications] by searching for "Dynamix Stop Shell" or visiting the [Dynamix Stop Shell plugin] directly.docs/unraid-os/using-unraid-to/manage-storage/array/replacing-disks-in-array.mdx (1)
209-216: Minor: Consider improving wording variety in prerequisites section.The static analysis tool flagged several repeated "If" structures in this section (lines 213-216). While the content is accurate, rephrasing for variety could improve readability. For example:
- Line 209: Consider "whether" instead of "if...or" for formality
- Lines 215-216: Consolidate or vary the repeated "If the drive is..." conditions
These are optional style improvements that would enhance accessibility without changing meaning.
docs/unraid-os/using-unraid-to/manage-storage/array/array-health-and-maintenance.mdx (1)
65-66: Consider replacing emoji buttons with descriptive text for better accessibility.Using emoji (🔘, 🟢) to represent UI buttons may not render or communicate clearly on all devices or for screen readers. Replacing them with text descriptions would improve accessibility.
Example:
- - 🔘 button - **Spin Up** (if currently spun down) - - 🟢 button - **Spin Down** (if currently spinning) + - **Spin Up button** (if currently spun down) + - **Spin Down button** (if currently spinning)docs/unraid-os/using-unraid-to/manage-storage/array/adding-disks-to-array.mdx (1)
26-26: Consider reducing phrase repetition to improve readability.LanguageTool flags at lines 26 and 30 suggest "want to use" is repeated nearby. Line 152 flags "additional %%parity disk|parity-drives%%" as potentially redundant. While these are stylistic, you could improve variety:
Line 26 context: replace one instance of "want to use" with "prefer" or "select"
Line 30 context: similar repetition
Line 152: "add an additional %%parity disk|parity-drives%%" → "add another %%parity disk|parity-drives%%" or just "add a second %%parity disk|parity-drives%%"Also applies to: 30-30, 152-152
docs/unraid-os/using-unraid-to/manage-storage/shares.mdx (1)
175-175: Minor: Consider replacing "in conjunction with" with shorter phrasing.Line 175:
"...works in conjunction with..."is flagged as wordy. For brevity, consider:"...works with..."or"...combined with...".
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (44)
.markdownlint.json(1 hunks).remarkrc.mjs(2 hunks)docs/unraid-os/advanced-configurations/optimize-storage/zfs-storage.mdx(1 hunks)docs/unraid-os/getting-started/what-is-unraid.mdx(1 hunks)docs/unraid-os/release-notes/7.2.0.md(13 hunks)docs/unraid-os/system-administration/advanced-tools/command-line-interface.mdx(19 hunks)docs/unraid-os/system-administration/maintain-and-update/changing-the-flash-device.mdx(1 hunks)docs/unraid-os/system-administration/maintain-and-update/upgrading-unraid.mdx(3 hunks)docs/unraid-os/system-administration/secure-your-server/partials/reset-password-advanced.mdx(1 hunks)docs/unraid-os/system-administration/secure-your-server/partials/reset-password-basic.mdx(1 hunks)docs/unraid-os/troubleshooting/common-issues/data-recovery.mdx(1 hunks)docs/unraid-os/troubleshooting/common-issues/partials/data-recovery/repair-xfs.mdx(1 hunks)docs/unraid-os/troubleshooting/common-issues/system-crashes-and-stability.mdx(1 hunks)docs/unraid-os/troubleshooting/common-issues/unclean-shutdowns.mdx(4 hunks)docs/unraid-os/troubleshooting/faq.mdx(2 hunks)docs/unraid-os/troubleshooting/licensing-faq.mdx(6 hunks)docs/unraid-os/using-unraid-to/create-virtual-machines/vm-setup.mdx(13 hunks)docs/unraid-os/using-unraid-to/create-virtual-machines/windows-on-a-vm.mdx(1 hunks)docs/unraid-os/using-unraid-to/manage-storage/apple-time-machine.mdx(2 hunks)docs/unraid-os/using-unraid-to/manage-storage/array-configuration.mdx(0 hunks)docs/unraid-os/using-unraid-to/manage-storage/array/_category_.json(1 hunks)docs/unraid-os/using-unraid-to/manage-storage/array/adding-disks-to-array.mdx(1 hunks)docs/unraid-os/using-unraid-to/manage-storage/array/array-health-and-maintenance.mdx(1 hunks)docs/unraid-os/using-unraid-to/manage-storage/array/overview.mdx(1 hunks)docs/unraid-os/using-unraid-to/manage-storage/array/removing-disks-from-array.mdx(1 hunks)docs/unraid-os/using-unraid-to/manage-storage/array/replacing-disks-in-array.mdx(1 hunks)docs/unraid-os/using-unraid-to/manage-storage/cache-pools.mdx(8 hunks)docs/unraid-os/using-unraid-to/manage-storage/file-systems.mdx(13 hunks)docs/unraid-os/using-unraid-to/manage-storage/partials/array-check-parity.mdx(1 hunks)docs/unraid-os/using-unraid-to/manage-storage/partials/btrfs-balance.mdx(0 hunks)docs/unraid-os/using-unraid-to/manage-storage/partials/btrfs-scrub.mdx(0 hunks)docs/unraid-os/using-unraid-to/manage-storage/partials/file-system-btrfs.mdx(0 hunks)docs/unraid-os/using-unraid-to/manage-storage/partials/file-system-xfs.mdx(0 hunks)docs/unraid-os/using-unraid-to/manage-storage/partials/file-system-zfs.mdx(0 hunks)docs/unraid-os/using-unraid-to/manage-storage/partials/move-array-to-pool.mdx(1 hunks)docs/unraid-os/using-unraid-to/manage-storage/partials/move-between-pools-using-mover.mdx(1 hunks)docs/unraid-os/using-unraid-to/manage-storage/partials/move-pool-to-array.mdx(1 hunks)docs/unraid-os/using-unraid-to/manage-storage/partials/remove-disk-command-line.mdx(2 hunks)docs/unraid-os/using-unraid-to/manage-storage/partials/remove-disk-gui.mdx(1 hunks)docs/unraid-os/using-unraid-to/manage-storage/shares.mdx(11 hunks)docs/unraid-os/using-unraid-to/run-docker-containers/community-applications.mdx(1 hunks)docusaurus.config.ts(10 hunks)scripts/format-crowdin-spacing.js(16 hunks)sitebar-semver-sort.d.ts(1 hunks)
💤 Files with no reviewable changes (6)
- docs/unraid-os/using-unraid-to/manage-storage/partials/file-system-btrfs.mdx
- docs/unraid-os/using-unraid-to/manage-storage/partials/btrfs-balance.mdx
- docs/unraid-os/using-unraid-to/manage-storage/array-configuration.mdx
- docs/unraid-os/using-unraid-to/manage-storage/partials/file-system-zfs.mdx
- docs/unraid-os/using-unraid-to/manage-storage/partials/file-system-xfs.mdx
- docs/unraid-os/using-unraid-to/manage-storage/partials/btrfs-scrub.mdx
🧰 Additional context used
🧠 Learnings (3)
📚 Learning: 2025-09-17T16:28:59.403Z
Learnt from: elibosley
Repo: unraid/docs PR: 325
File: docs/unraid-os/system-administration/maintain-and-update/changing-the-flash-device.mdx:123-131
Timestamp: 2025-09-17T16:28:59.403Z
Learning: Unraid's flash backup feature (accessed via Main tab → Flash device → FLASH BACKUP) creates complete installation ZIP files that include both the Unraid OS and user configuration. These backup ZIPs are compatible with the USB Flash Creator's "Use custom" option for restoring to new flash devices.
Applied to files:
docs/unraid-os/system-administration/maintain-and-update/upgrading-unraid.mdxdocs/unraid-os/release-notes/7.2.0.mddocs/unraid-os/system-administration/maintain-and-update/changing-the-flash-device.mdxdocs/unraid-os/getting-started/what-is-unraid.mdxdocs/unraid-os/troubleshooting/common-issues/data-recovery.mdxdocs/unraid-os/using-unraid-to/create-virtual-machines/vm-setup.mdxdocs/unraid-os/system-administration/secure-your-server/partials/reset-password-basic.mdx
📚 Learning: 2025-09-28T04:47:45.534Z
Learnt from: elibosley
Repo: unraid/docs PR: 339
File: docs/unraid-os/getting-started/what-is-unraid.mdx:64-80
Timestamp: 2025-09-28T04:47:45.534Z
Learning: In Docusaurus MDX files, `mdx-code-block` is not a literal code block but an escape hatch for Crowdin translation integration. It's a no-op wrapper that allows complex JSX to be preserved during Crowdin upload/download cycles while still rendering normally. Docusaurus includes special handling that unwraps these blocks so the JSX content renders as intended.
Applied to files:
scripts/format-crowdin-spacing.js
📚 Learning: 2025-09-16T15:34:45.481Z
Learnt from: elibosley
Repo: unraid/docs PR: 321
File: crowdin.yml:10-11
Timestamp: 2025-09-16T15:34:45.481Z
Learning: In the unraid/docs repository, the Crowdin configuration uses a broad `/docs/**/*` source pattern and relies on overriding the v1 parser to use the v2 parser at the Crowdin project settings level, rather than specifying `type: mdx_v2` in crowdin.yml.
Applied to files:
scripts/format-crowdin-spacing.jsdocusaurus.config.ts
🧬 Code graph analysis (2)
scripts/format-crowdin-spacing.js (2)
.remarkrc.mjs (3)
lines(145-145)indent(152-152)indent(160-160)scripts/format-crowdin-spacing.test.js (1)
processContent(5-5)
.remarkrc.mjs (1)
scripts/format-crowdin-spacing.js (9)
normalized(146-146)normalized(159-159)normalized(169-169)normalized(194-194)indent(132-132)indent(353-353)colons(133-133)rest(134-134)i(313-313)
🪛 Gitleaks (8.28.0)
docs/unraid-os/system-administration/advanced-tools/command-line-interface.mdx
[high] 479-479: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
[high] 544-544: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
🪛 LanguageTool
docs/unraid-os/using-unraid-to/manage-storage/array/replacing-disks-in-array.mdx
[style] ~170-~170: Consider using a different verb for a more formal wording.
Context: ...-reports-and-disk-health.mdx). - You've fixed any external problems that caused the d...
(FIX_RESOLVE)
[style] ~194-~194: Consider using a different verb to strengthen your wording.
Context: ...%Maintenance Mode|maintenance-mode%% to speed up the rebuild process. 9. Click Start...
(SPEED_UP_ACCELERATE)
[style] ~209-~209: In contexts where ‘if’ is followed by ‘or’, using ‘whether’ may be more appropriate (and formal).
Context: ...rrent parity disk. This isn't necessary if your new data drive is the same size or...
(IF_WHETHER)
[style] ~215-~215: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...sabled. If the drive is healthy but you want to replace it, unassign the drive and star...
(REP_WANT_TO_VB)
[style] ~216-~216: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... force Unraid to mark it as disabled. - If your replacement data drive is not larg...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
docs/unraid-os/troubleshooting/licensing-faq.mdx
[style] ~29-~29: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...sh device?](#manual-keyfile-install) - [How can I determine my registration type?](...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~36-~36: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: .../RC versions)?](#pre-release-policy) - [What does "unlimited" mean for attached stor...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
docs/unraid-os/release-notes/7.2.0.md
[style] ~174-~174: Consider using the internationally preferred transliteration for the capital of Ukraine.
Context: ...ireGuard tunnels - Improvement: Europe/Kiev timezone renamed to Europe/Kyiv to a...
(KIEV)
docs/unraid-os/system-administration/advanced-tools/command-line-interface.mdx
[locale-violation] ~491-~491: In American English, ‘afterward’ is the preferred variant. ‘Afterwards’ is more commonly used in British English and other dialects.
Context: ...er/or/mnt/diskX` share. 5. Clean up afterwards: ```bash umount /work rmdir /...
(AFTERWARDS_US)
docs/unraid-os/using-unraid-to/manage-storage/array/array-health-and-maintenance.mdx
[style] ~152-~152: Consider using a different verb for a more formal wording.
Context: ...art, follow these steps to identify and fix common problems. Look for error message...
(FIX_RESOLVE)
docs/unraid-os/using-unraid-to/manage-storage/array/adding-disks-to-array.mdx
[style] ~26-~26: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...l be formatted with %%XFS|xfs%%. If you want to use %%ZFS|zfs%% or %%BTRFS|btrfs%% inst...
(REP_WANT_TO_VB)
[style] ~30-~30: This phrase is redundant. Consider writing “filled”.
Context: ...quires disks to be in a cleared state - completely filled with zeros and marked with a special si...
(COMPLETELY_ANNIHILATE)
[style] ~152-~152: This phrase might be redundant. Consider either removing or replacing the adjective ‘additional’.
Context: ... use larger-sized disks in the array or add an additional %%parity disk|parity-drives%%. :::caution If y...
(ADD_AN_ADDITIONAL)
docs/unraid-os/using-unraid-to/manage-storage/shares.mdx
[style] ~93-~93: Consider using the synonym “brief” (= concise, using a few words, not lasting long) to strengthen your wording.
Context: ...al settings: - Comments: Write a short description to identify your share (e.g...
(QUICK_BRIEF)
[style] ~175-~175: ‘in conjunction with’ might be wordy. Consider a shorter alternative.
Context: ...he Minimum Free Space setting works in conjunction with the %%allocation method|allocation-meth...
(EN_WORDINESS_PREMIUM_IN_CONJUNCTION_WITH)
[grammar] ~357-~357: Use a hyphen to join words.
Context: ...rive nears capacity. ::: --- ### Split level The Split Level setting in Un...
(QB_NEW_EN_HYPHEN)
[grammar] ~525-~525: Use a hyphen to join words.
Context: ...file-transfer-operations) in the Command line interface documentation. :::
(QB_NEW_EN_HYPHEN)
docs/unraid-os/using-unraid-to/manage-storage/array/overview.mdx
[style] ~54-~54: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...l be formatted with %%XFS|xfs%%. If you want to use %%ZFS|zfs%% or %%BTRFS|btrfs%% inst...
(REP_WANT_TO_VB)
docs/unraid-os/using-unraid-to/manage-storage/file-systems.mdx
[style] ~214-~214: This phrase is redundant. Consider using “outside”.
Context: ...that files at the root of the drive are outside of any Shares and will not be moved. - ...
(OUTSIDE_OF)
[uncategorized] ~375-~375: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...b operations are usually quicker than a full disk scan because they only check allocated ...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
[style] ~579-~579: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...intenance-mode%%** for a repair. - For %%ZFS|zfs%%: Use Normal mode and ...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: deploy-preview
🔇 Additional comments (41)
docs/unraid-os/using-unraid-to/manage-storage/partials/remove-disk-gui.mdx (1)
1-20: Documentation structure and formatting look good for accessibility improvements.The changes appropriately standardize the list formatting (converting to positive step numbers) and remove unnecessary bold formatting from the step descriptions themselves, while preserving bold for UI element references like "Main" and "Balance Status". This aligns well with the PR's accessibility improvement goals.
The prerequisite note, steps, and timing note are clearly organized and the instructions appear accurate and actionable. The glossary substitution syntax (e.g.,
%%array|array%%,%%RAID|raid%%) is consistent throughout.docs/unraid-os/system-administration/secure-your-server/partials/reset-password-advanced.mdx (1)
11-16: Clear and accurate documentation update.The change correctly demonstrates the shadow file entry before and after removing the root password hash. The new example properly shows an empty password field (
::) following removal, which accurately reflects the expected state when no password is set.docs/unraid-os/using-unraid-to/manage-storage/apple-time-machine.mdx (3)
95-106: Cosmetic formatting changes look good.The numbered list formatting in the "Multiple Time Machine setups" section has been standardized for consistency and readability. Steps are clearly numbered, indentation is proper, and sub-bullets with hyphens follow a consistent pattern.
113-115: Troubleshooting steps formatting is consistent and clear.The three troubleshooting items are properly numbered and formatted with consistent wording and capitalization. The punctuation and structure facilitate easy scanning for users seeking solutions.
39-57: Share configuration instructions and table are well-structured.The table clearly documents each %%SMB|samba%% share setting with practical guidance. Relative link to
./shares.mdxis correctly formatted for internal wiki documentation per the PR checklist.docs/unraid-os/using-unraid-to/create-virtual-machines/windows-on-a-vm.mdx (1)
289-289: Heading reformatting aligns with accessibility improvements.Removing bold formatting from the numbered list item and converting to plain text improves semantic clarity for screen readers and accessibility tools. This change is consistent with the PR's goal to improve documentation accessibility.
docs/unraid-os/troubleshooting/licensing-faq.mdx (3)
11-49: Index section improves documentation navigation and accessibility.The new categorized index with anchor links is a solid accessibility improvement. It enables users to jump directly to relevant sections and provides a clear overview of FAQ structure. Anchor links are correctly matched to section IDs throughout the file.
85-101: Iframe implementation follows accessibility best practices.The embedded Loom video includes proper accessibility attributes (
title,allowfullscreenvariants,allowpermissions). The centered flexbox wrapper is semantically appropriate for layout purposes.
1-259: Verify table accessibility within centered flexbox wrappers.Tables at lines 121–126 and 200–204 are now wrapped in
display: flexdivs for centering. While this works visually, ensure that screen readers and responsive layouts handle table overflow/scrolling correctly. This is especially important on mobile viewports where the table might exceed container width.Consider testing: (1) screen reader experience when navigating wrapped tables, (2) table responsiveness/overflow behavior on narrow viewports, (3) whether adding
style={{ overflowX: 'auto' }}to the wrapper would improve mobile UX without breaking accessibility.docs/unraid-os/using-unraid-to/create-virtual-machines/vm-setup.mdx (3)
6-7: Import style aligned with PR standardization.The shift from single to double quotes for Theme component imports is consistent with MDX/JavaScript conventions and clean. This change is good.
171-249: Verify that Tabs component retention aligns with PR objectives.This file still contains the
<Tabs>component with threeTabItemchildren (Creating snapshots, Managing snapshots, Reverting to snapshots). The PR objective mentions "flatten tabbed content and improve documentation accessibility," but the tabs remain unchanged here.Please clarify: Is this intentional (e.g., tabs being flattened only in other files), or should these tabs be converted to a flattened format in this file as well?
1-585: Formatting and whitespace changes appear clean.The line reflowing, whitespace adjustments, and list formatting throughout the file are consistent and don't introduce readability issues. Internal links continue to use relative paths correctly (e.g.,
./overview-and-system-prep.mdx,../manage-storage/shares.mdx). The special templating syntax (%%...%%) remains intact.docs/unraid-os/system-administration/advanced-tools/command-line-interface.mdx (4)
474-488: Gitleaks warnings are false positives—documentation examples use placeholder credentials.The static analysis flagged lines 479 and 544 as potential API key exposure, but these are false positives. The mount commands show placeholder values (
username=youruser,password=yourpassword) clearly marked as a template in the preceding comments (lines 474–476). This is appropriate for documentation: it shows users the proper syntax while using obviously non-real values.Additionally, the security note (lines 485–488) correctly advises against passing passwords on the command line and recommends using an interactive prompt or protected credentials file—aligned with best practices.
No action needed; this is documentation correctly demonstrating credential handling patterns.
442-572: New "File transfer operations" section is well-structured and accessible.The addition of comprehensive file transfer documentation (lines 442–572) aligns well with the PR objective to improve documentation accessibility. The section thoughtfully provides multiple approaches:
- Midnight Commander (lines 446–499): Leverages built-in tooling, no extra installation needed
- Krusader (lines 500–514): GUI option for users preferring graphical interfaces
- Command-line methods (lines 516–572): For automation and advanced users
The inclusion of security best practices—explicitly warning against passing passwords on the command line and recommending credentials files with proper permissions—demonstrates responsible documentation. The
iocharset=utf8guidance for international filenames is also a helpful detail that prevents user frustration.
45-440: Documentation restructuring and reformatting improves clarity and scannability.The extensive reformatting across the existing sections (command examples, system monitoring, storage utilities, network diagnostics) consistently improves documentation quality:
- Converting to collapsible
<details>sections reduces cognitive load and improves page scannability- Adding language tags to all code blocks enables proper syntax highlighting
- Emphasizing command examples first, followed by explanation, makes documentation more action-oriented
- Internal cross-references and Unraid-specific terminology (web-gui, ssh, array, root-user) are preserved
The structure maintains all original content while significantly improving usability. Relative paths are used appropriately for internal documentation links.
8-10: ✓ Import paths verified and correct.All three imported partials exist at the expected locations and resolve correctly:
./partials/command-line-interface/cpu-info.mdx✓./partials/command-line-interface/memory-info.mdx✓./partials/command-line-interface/storage-info.mdx✓The relative paths in lines 8-10 are valid after restructuring.
docs/unraid-os/troubleshooting/common-issues/unclean-shutdowns.mdx (6)
6-7: Verify Tabs/TabItem imports are necessary throughout the file.These imports are present but used only in the VM hibernation section (lines 96-155). Given the PR objective to flatten tabbed content, confirm whether the remaining tabs in that section are intentional or should also be flattened.
37-63: Excellent flattening of tabbed events content.This section successfully replaces previously tabbed imports with inline, accessible subsections. The content is now:
- More accessible to screen readers and keyboard navigation
- Easier to search and index
- Better for scannability with clear section headers
- Properly structured with consistent heading hierarchy
This achieves the PR objective of improving documentation accessibility.
96-155: Clarify scope of tab-flattening PR objective.This VM hibernation section (lines 96-155) still uses Tabs/TabItem for multi-OS setup instructions. This appears inconsistent with the PR title "flatten tabbed content," whereas the events section (lines 37-63) successfully flattens tabs into linear sections.
Questions:
- Is keeping tabs here intentional (platform-selection tabs are acceptable)?
- Should these also be flattened into separate OS-labeled sections?
- Was the PR scope limited to specific tab types?
Please clarify so reviewers understand the intended approach.
171-175: Verify timeout configuration values are accurate.The configuration table provides default and recommended timeout values. Please confirm these values are:
- Accurate for current Unraid version
- Tested and reliable
- Aligned with any upstream documentation or community best practices
1-323: Solid documentation restructuring with strong accessibility improvements.What's working well:
- ✅ Successfully flattened tabbed events into linear, accessible sections (lines 37-63)
- ✅ Proper use of admonition blocks (:::tip, :::warning, :::caution, :::note) for visual hierarchy
- ✅ Internal links follow PR requirements (relative paths, .mdx extension, lowercase dash-separated names)
- ✅ Well-organized timeout configuration guide with practical formula (lines 167-323)
- ✅ Comprehensive VM hibernation instructions with OS-specific guidance
Items needing clarification:
- Tabs remain in VM hibernation section (lines 96-155) — confirm if this is intentional or should also be flattened
- Verify internal links resolve (see separate verification comments above)
- Confirm timeout recommendations are current and tested
This PR demonstrates a solid approach to improving documentation accessibility. The content is comprehensive and well-structured.
19-19: Links verified as correct and functional.All internal wiki links have been confirmed to exist and point to valid sections:
../diagnostics/capture-diagnostics-and-logs.mdx#persistent-logs-syslog-server— File and anchor both exist../../using-unraid-to/manage-storage/array/overview.mdx#startstop-the-array— File and anchor both existRelative paths are correctly calculated from the source file location.
docs/unraid-os/using-unraid-to/run-docker-containers/community-applications.mdx (2)
63-75: Verify tabbed content aligns with PR goals.The file still imports and uses Tabs/TabItem components (lines 6, 63-75), while the PR objective states "flatten tabbed content." Please clarify whether this retention is intentional (e.g., organizing application management tasks) or should be refactored to heading-based sections to match the flattening goal described in the PR.
16-16: Link update to new array documentation path is correct.The link has been properly updated from
../manage-storage/array-configuration.mdxto../manage-storage/array/overview.mdx, aligning with the new array subdirectory structure. The glossary term syntax (%%array|array%%) and markdown formatting remain intact.docs/unraid-os/system-administration/maintain-and-update/changing-the-flash-device.mdx (1)
169-169: Verify parity-checks anchor exists in target file.The link anchor has been updated from
#parity--read-checksto#parity-checks. Please confirm that the section "## parity-checks" (or equivalent heading) exists inarray/array-health-and-maintenance.mdxto avoid broken anchor links. The path itself is correct, but anchor mismatches would result in users landing on the wrong section.docs/unraid-os/troubleshooting/common-issues/system-crashes-and-stability.mdx (1)
178-178: Verify parity-checks anchor in array-health-and-maintenance.mdx.The parity check link anchor has been changed from
#parity--read-checksto#parity-checks. Ensure this anchor matches the actual section heading in the target file to prevent broken links.docs/unraid-os/using-unraid-to/manage-storage/partials/move-array-to-pool.mdx (1)
9-14: Step reformatting improves readability and accessibility.The steps have been converted from bold-numbered markers to inline sentences, which improves screen reader compatibility and reduces visual clutter. The substantive action sequence (disable services → configure shares → run mover → verify → re-enable) is preserved clearly.
docs/unraid-os/using-unraid-to/manage-storage/partials/move-pool-to-array.mdx (1)
9-13: Clear step instructions with specific verification guidance.The inline formatting improves readability, and the specific verification step (checking via folder icon on Main tab) provides concrete guidance for users to confirm the move succeeded.
docs/unraid-os/using-unraid-to/manage-storage/partials/move-between-pools-using-mover.mdx (1)
1-10: Consolidated step structure maintains clarity for complex workflow.The consolidation of the "disable services" step into Step 1 and the addition of "(if needed)" to re-enable makes the instructions more concise without sacrificing clarity. The nested substeps for the two-phase pool transition (pool1→array→pool2) are well-organized.
docs/unraid-os/using-unraid-to/manage-storage/array/removing-disks-from-array.mdx (1)
1-77: Comprehensive new documentation covering both parity and data disk removal.This new page provides clear guidance for disk removal scenarios with appropriate risk warnings. The distinction between standard (with parity sync) and parity-preserve (advanced, data-erasing) methods is well-explained, and the version-specific
ddcommands (6.12+ vs 6.11 and earlier) are helpful. Admonitions appropriately highlight risks and best practices.docs/unraid-os/using-unraid-to/manage-storage/array/replacing-disks-in-array.mdx (2)
1-50: Excellent coverage of disk replacement scenarios with clear prerequisites and cautions.The documentation clearly distinguishes between capacity upgrades and failed-disk replacements, with appropriate risk warnings for different parity configurations. Prerequisites are well-explained, and the backup guidance for old disks is a valuable safety consideration.
205-265: Parity swap section provides valuable guidance for complex hardware transitions.The parity swap procedure is well-documented with clear prerequisites and a detailed step-by-step workflow. The example scenario effectively illustrates when and why this procedure is needed. The warnings about SMART verification and preclearning are appropriate for risk mitigation.
docs/unraid-os/using-unraid-to/manage-storage/file-systems.mdx (2)
64-84: Ensure NTFS/exFAT parity warning is clear and prominent.Lines 68-78 include an important warning about adding NTFS/exFAT drives before parity. This is critical to prevent data loss. The warning is well-placed, but verify:
- The order requirement (NTFS/exFAT drives → then parity) is correct per Unraid's behavior
- The consequences are clearly stated (drives will be zeroed if added after parity)
This appears accurate, but this should be verified against Unraid's actual implementation to ensure users don't encounter data loss.
207-225: Link reference is correct; no action needed.The heading "### Using 'mover' to empty an array disk" exists at line 155 of
docs/unraid-os/release-notes/7.0.0.md. Markdown auto-generates the anchor by converting the heading to lowercase, replacing spaces with hyphens, and removing apostrophes—resulting inusing-mover-to-empty-an-array-disk. This matches the reference link exactly at line 218 of the file under review.docs/unraid-os/using-unraid-to/manage-storage/partials/remove-disk-command-line.mdx (1)
25-31: Verify if "forget" procedure is still necessary in current Unraid.Lines 25-31 describe a multi-step "forget" procedure (stop array, unassign, start, clear config). This seems complex for what should be a straightforward device removal. Confirm whether this step is:
- Still necessary in Unraid 6.12+ (mentioned in PR context)
- Actually needed after btrfs device remove command, or if the command handles this automatically
- If truly necessary, consider whether it should be marked as optional or if there's a simpler alternative
docs/unraid-os/using-unraid-to/manage-storage/array/overview.mdx (1)
52-57: All cross-reference links are valid and files exist.Verification confirms that all sibling array management pages referenced in overview.mdx exist in the array/ subdirectory, and the parent-level file-systems.mdx reference is also correct. The relative paths (./filename.mdx and ../file-systems.mdx) will resolve properly during documentation builds.
docs/unraid-os/using-unraid-to/manage-storage/shares.mdx (1)
30-30: Terminology inconsistency detected—standardization incomplete across codebase.The verification confirms your concern. While the modified shares.mdx file uses glossary-wrapped terminology (
%%VM|vm%%,%%web-gui%%), many other documentation files throughout the codebase still use plain text variants like "VM Manager" and "WebGUI". This creates inconsistency:
- Release notes files contain numerous instances of plain "VM Manager" (e.g.,
Settings → VM Manager)- Other mdx files reference "VM Manager" without glossary wrapping
- WebGUI usage appears properly wrapped, but VM Manager is not uniformly applied
Recommendation: Either extend the terminology standardization across all documentation files in the PR, or revert to match the existing codebase convention for consistency. Decide on scope before merging.
docs/unraid-os/using-unraid-to/manage-storage/cache-pools.mdx (2)
46-52: All partial imports verified and no broken cross-references detected.Tab flattening is correctly implemented. All 8 partial components exist and can render:
partials/remove-disk-gui.mdxpartials/remove-disk-command-line.mdxpartials/pool-single-device-mode.mdxpartials/pool-multi-device-mode.mdxpartials/move-pool-to-array.mdxpartials/move-array-to-pool.mdxpartials/move-between-pools-using-mover.mdxpartials/move-between-pools-manual.mdxExternal references from three other documents (community-applications.mdx, windows-on-a-vm.mdx, array/overview.mdx) all link to the document root without tab-specific anchors, so no links are broken by the tab removal. Heading-based anchors work correctly with the flattened structure.
17-17: Update cross-references in all internationalized versions; remove old array-configuration.mdx files from i18n directories.The PR partially completed the cross-reference update. While the English
docs/version was updated, the internationalized versions still reference the oldarray-configuration.mdxpath:
i18n/zh/docusaurus-plugin-content-docs/current/unraid-os/using-unraid-to/manage-storage/cache-pools.mdx:19still references./array-configuration.mdxi18n/fr/docusaurus-plugin-content-docs/current/unraid-os/using-unraid-to/manage-storage/cache-pools.mdx:19still references./array-configuration.mdxi18n/de/docusaurus-plugin-content-docs/current/unraid-os/using-unraid-to/manage-storage/cache-pools.mdx:19still references./array-configuration.mdxi18n/es/docusaurus-plugin-content-docs/current/unraid-os/using-unraid-to/manage-storage/cache-pools.mdx:19still references./array-configuration.mdxAdditionally, the old
array-configuration.mdxfiles still exist in all i18n directories, and numerous other references throughout the i18n translations still point to the old path structure.⛔ Skipped due to learnings
Learnt from: elibosley Repo: unraid/docs PR: 321 File: crowdin.yml:10-11 Timestamp: 2025-09-16T15:34:45.481Z Learning: In the unraid/docs repository, the Crowdin configuration uses a broad `/docs/**/*` source pattern and relies on overriding the v1 parser to use the v2 parser at the Crowdin project settings level, rather than specifying `type: mdx_v2` in crowdin.yml.docs/unraid-os/system-administration/maintain-and-update/upgrading-unraid.mdx (2)
152-159: Formatting improvements enhance readability and accessibility.The reformatting from verbose bolded descriptive items to concise, action-oriented imperative sentences improves clarity and scanability. The numbered lists are well-structured and remain logically consistent with the original content flow.
Also applies to: 166-172, 192-197, 205-210
1-212: All documentation cross-references are valid and accessible.Verification confirms that all imported partial files and cross-referenced documentation paths exist and resolve correctly:
- 4 imported partials: All found and accessible
- 8 content cross-references: All found and resolve to valid files
- Result: 0 missing files, 100% resolution success
No issues detected.
docs/unraid-os/system-administration/advanced-tools/command-line-interface.mdx
Outdated
Show resolved
Hide resolved
docs/unraid-os/using-unraid-to/manage-storage/array/adding-disks-to-array.mdx
Show resolved
Hide resolved
- 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.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (4)
docs/unraid-os/system-administration/advanced-tools/command-line-interface.mdx (2)
384-396: Fix indentation inconsistency in TabItem elements.The memory TabItem (line 389) lacks proper indentation relative to the CPU and Storage TabItems. This creates a visual inconsistency in the source code.
<Tabs> <TabItem value="cpu" label="CPU info"> <CliCpuInfo /> </TabItem> -<TabItem value="memory" label="Memory info"> - <CliMemoryInfo /> -</TabItem> + <TabItem value="memory" label="Memory info"> + <CliMemoryInfo /> + </TabItem> <TabItem value="storage" label="Storage info"> <CliStorageInfo /> </TabItem> </Tabs>
547-549: Consider formatting the security note for clarity.The security guidance on lines 547–548 is valuable but embedded within plain text. Consider extracting it into a callout block (:::caution or similar) for better visibility, consistent with the caution block later in the section (lines 574–579).
1. Copy files: - You can use `cp`: ```bash cp -r /work/* /mnt/disk1 ``` - Or, use `rsync` for detailed progress: ```bash rsync -av --progress /work/ /mnt/disk1/ ``` 1. Unmount and remove the temporary directory: ```bash umount /work rmdir /work ``` -**Security note:** Do not pass passwords on the command line. Use an -interactive prompt or a credentials file with strict permissions instead. +:::caution +Do not pass passwords on the command line. Use an interactive prompt or a credentials file with strict permissions instead. +:::docs/unraid-os/using-unraid-to/manage-storage/array/replacing-disks-in-array.mdx (1)
169-171: Optional: Strengthen language for formal tone.Per static analysis, consider replacing "You've fixed" with more formal wording to maintain consistent documentation tone. Example suggestions:
- "You've resolved any external problems"
- "You've corrected any external problems"
This improves the formality and consistency of the documentation style.
docs/unraid-os/using-unraid-to/manage-storage/array/adding-disks-to-array.mdx (1)
30-30: Minor: Remove redundant modifier.The phrase "completely filled with zeros" is slightly verbose. "Filled with zeros" alone conveys the complete action.
-Unraid requires disks to be in a cleared state - completely filled with zeros and marked with a special signature - before adding them to a parity-protected array. This process ensures parity integrity and keeps the array online during disk preparation. +Unraid requires disks to be in a cleared state - filled with zeros and marked with a special signature - before adding them to a parity-protected array. This process ensures parity integrity and keeps the array online during disk preparation.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (7)
.remarkrc.mjs(2 hunks)docs/unraid-os/system-administration/advanced-tools/command-line-interface.mdx(19 hunks)docs/unraid-os/troubleshooting/licensing-faq.mdx(6 hunks)docs/unraid-os/using-unraid-to/manage-storage/array/adding-disks-to-array.mdx(1 hunks)docs/unraid-os/using-unraid-to/manage-storage/array/replacing-disks-in-array.mdx(1 hunks)docusaurus.config.ts(10 hunks)sidebar-semver-sort.d.ts(1 hunks)
🧰 Additional context used
🧠 Learnings (2)
📓 Common learnings
Learnt from: elibosley
Repo: unraid/docs PR: 321
File: crowdin.yml:10-11
Timestamp: 2025-09-16T15:34:45.481Z
Learning: In the unraid/docs repository, the Crowdin configuration uses a broad `/docs/**/*` source pattern and relies on overriding the v1 parser to use the v2 parser at the Crowdin project settings level, rather than specifying `type: mdx_v2` in crowdin.yml.
📚 Learning: 2025-09-16T15:34:45.481Z
Learnt from: elibosley
Repo: unraid/docs PR: 321
File: crowdin.yml:10-11
Timestamp: 2025-09-16T15:34:45.481Z
Learning: In the unraid/docs repository, the Crowdin configuration uses a broad `/docs/**/*` source pattern and relies on overriding the v1 parser to use the v2 parser at the Crowdin project settings level, rather than specifying `type: mdx_v2` in crowdin.yml.
Applied to files:
docusaurus.config.ts
🧬 Code graph analysis (1)
.remarkrc.mjs (1)
scripts/format-crowdin-spacing.js (12)
lines(122-122)lines(300-300)normalized(146-146)normalized(159-159)normalized(169-169)normalized(194-194)line(314-314)indent(132-132)indent(353-353)colons(133-133)rest(134-134)i(313-313)
🪛 LanguageTool
docs/unraid-os/using-unraid-to/manage-storage/array/adding-disks-to-array.mdx
[style] ~26-~26: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...l be formatted with %%XFS|xfs%%. If you want to use %%ZFS|zfs%% or %%BTRFS|btrfs%% inst...
(REP_WANT_TO_VB)
[style] ~30-~30: This phrase is redundant. Consider writing “filled”.
Context: ...quires disks to be in a cleared state - completely filled with zeros and marked with a special si...
(COMPLETELY_ANNIHILATE)
[style] ~152-~152: This phrase might be redundant. Consider either removing or replacing the adjective ‘additional’.
Context: ... use larger-sized disks in the array or add an additional %%parity disk|parity-drives%%. :::caution If y...
(ADD_AN_ADDITIONAL)
docs/unraid-os/using-unraid-to/manage-storage/array/replacing-disks-in-array.mdx
[style] ~170-~170: Consider using a different verb for a more formal wording.
Context: ...-reports-and-disk-health.mdx). - You've fixed any external problems that caused the d...
(FIX_RESOLVE)
[style] ~194-~194: Consider using a different verb to strengthen your wording.
Context: ...%Maintenance Mode|maintenance-mode%% to speed up the rebuild process. 9. Click Start...
(SPEED_UP_ACCELERATE)
[style] ~209-~209: In contexts where ‘if’ is followed by ‘or’, using ‘whether’ may be more appropriate (and formal).
Context: ...rrent parity disk. This isn't necessary if your new data drive is the same size or...
(IF_WHETHER)
[style] ~215-~215: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...lready disabled. For healthy drives you want to replace, unassign the drive and start t...
(REP_WANT_TO_VB)
docs/unraid-os/troubleshooting/licensing-faq.mdx
[style] ~29-~29: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...sh device?](#manual-keyfile-install) - [How can I determine my registration type?](...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~36-~36: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: .../RC versions)?](#pre-release-policy) - [What does "unlimited" mean for attached stor...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: deploy-preview
🔇 Additional comments (28)
docs/unraid-os/troubleshooting/licensing-faq.mdx (5)
4-4: Accessibility improvement: Table of contents depth limiting.Adding
toc_max_heading_level: 2to the front matter improves documentation accessibility by controlling the depth of the generated table of contents, making navigation more focused and less cluttered.
11-49: Structured index improves navigation and accessibility.The new categorized index with subsection links is a strong accessibility improvement, providing users a clear overview of FAQ topics and quick access to sections. All anchor links use the correct MDX syntax (
{#id}).
119-132: Table centering wrapper improves visual presentation.Wrapping the Upgrade Path table with a centered flex container provides consistent visual formatting for license-related content and improves readability for users viewing tables.
198-206: Consistent table layout styling across documentation.The centered wrapper for the device limits table maintains layout consistency with the earlier upgrade path table, providing a cohesive visual experience for all license-related tables.
11-49: LanguageTool warnings in Index section are false positives.The static analysis flags warn about three successive sentences beginning with the same word at lines ~29 and ~36, but these are actually categorized list items in the Index section (e.g., "How do I..."), not prose sentences. These warnings can be safely disregarded as they don't represent legitimate style issues in this navigational context.
docs/unraid-os/system-administration/advanced-tools/command-line-interface.mdx (3)
442-580: Excellent addition of the "File transfer operations" section.The new comprehensive section on file transfer methods significantly improves documentation accessibility and reduces reliance on tabbed content. The structure is clear, progressing logically from graphical (Midnight Commander, Krusader) to command-line approaches, and includes appropriate security guidance throughout.
1-10: Imports and style standardization look good.Double quotes and relative paths for partials align well with the PR's objectives of standardizing string quotes and using relative file links for internal wiki documents.
212-212: Internal link path is correct and verified.The file
replacing-disks-in-array.mdxexists at the expected location under thearray/subdirectory, and the relative path../../using-unraid-to/manage-storage/array/replacing-disks-in-array.mdxcorrectly resolves from the source file.docs/unraid-os/using-unraid-to/manage-storage/array/replacing-disks-in-array.mdx (5)
116-116: Improve cross-reference wording at line 116.The phrase "follow the Parity Swap procedure" should link to the procedure. Verify that the internal reference resolves to the "Parity swap" section (line 205). Currently, it appears to be plain text without a link.
Suggested improvement:
-Make sure the new drive is at least as large as the failed drive but not larger than your smallest parity drive. If you have to use a larger drive, follow the Parity Swap procedure. +Make sure the new drive is at least as large as the failed drive but not larger than your smallest parity drive. If you have to use a larger drive, follow the [Parity swap](#parity-swap) procedure.
207-211: Approve parity swap section and scenario explanation.The parity swap section provides clear, detailed guidance with a concrete example scenario. The explanation of prerequisites and the step-by-step workflow is well-structured and should help users understand when and how to perform this critical operation.
1-266: Comprehensive documentation structure is well-organized.The article effectively covers multiple disk replacement scenarios with appropriate warnings and procedural guidance. The use of admonitions (:::warning, :::note, :::tip, :::important) is well-calibrated to highlight risks at appropriate points. Procedural steps are clear and numbered appropriately.
169-169: Cross-reference path is valid—no issues found.The relative path
../../system-administration/monitor-performance/smart-reports-and-disk-health.mdxcorrectly resolves from the current file location and the target file exists.
179-180: All cross-reference paths are valid.The three cross-references in lines 179-180 have been verified:
../../system-administration/advanced-tools/command-line-interface.mdx#smartctl— file exists,### \smartctl`` heading found../../troubleshooting/common-issues/data-recovery.mdx#running-the-repair— file exists,### Running the Repairheading foundNo issues detected.
docs/unraid-os/using-unraid-to/manage-storage/array/adding-disks-to-array.mdx (5)
10-14: Approve important prerequisite note.The important note clearly explains the size requirement when adding new data disks, which is critical for users to understand before starting the process. The cross-references to parity-drives are properly formatted.
68-95: Approve data disk addition procedures.The procedures for adding disks to parity-protected arrays (lines 72-88) and arrays without parity (lines 96-110) are clearly differentiated and well-structured. The important warnings about double-checking serial numbers before formatting are appropriately placed and emphasized.
128-149: Comprehensive parity explanation is thorough and accurate.The "Understanding parity" section provides a solid technical explanation covering:
- XOR operation mechanics (even parity)
- Reconstruction procedures
- Disk size requirements
- Performance implications
- Dual parity with Q-parity (Reed-Solomon explanation)
- RAID 6 comparison
The explanations balance technical depth with accessibility for users.
150-177: Approve parity upgrade section with good context.The parity upgrade procedure is clearly laid out. The caution about single-parity unprotected states and the tip about retaining the old disk are valuable safeguards. The distinction between upgrading a parity disk vs. the parity swap procedure is appropriately cross-referenced.
40-56: Table formatting is correct and properly structured.The verification confirms the markdown table at lines 40-56 is well-formed with proper syntax:
- Header and separator rows are correctly formatted
- All three columns are consistently aligned
- Four data rows contain expected content
- No character-level issues or malformed escapes detected
- The JSX styled div component properly wraps the markdown table
The MDX syntax is valid and should render without issues.
sidebar-semver-sort.d.ts (1)
1-16: LGTM! TypeScript declaration is well-structured.The module declaration correctly defines the public API for
sortSidebarItems. The type import from@docusaurus/plugin-content-docsensures proper type safety, and the function signature is clear and well-documented. The filename now appears to match the module declaration path and the import indocusaurus.config.ts(line 25), resolving the previous critical issue about the "sitebar" vs "sidebar" typo.docusaurus.config.ts (5)
1-26: Import path corrected and linting enhanced.The import at line 25 now correctly references
./sidebar-semver-sort.js, resolving the previous "sitebar" typo. The extensive addition of remark lint plugins (lines 8-23) significantly enhances documentation quality checks, covering list formatting, code blocks, headings, links, and general formatting rules.
190-190: Verify the table of contents depth reduction is intentional.The
maxHeadingLevelhas been reduced from 4 to 3, meaning fourth-level headings will no longer appear in the table of contents. While this may align with the PR's goal to flatten content and improve accessibility, please confirm this change is intentional and that no important navigation is lost, particularly in longer documentation pages that previously relied on h4 visibility in the TOC.
332-336: Array redirect paths corrected.The redirects now properly target
/unraid-os/using-unraid-to/manage-storage/array/overview/instead of the non-existent bare/array/path. This addresses the critical redirect issue flagged in the previous review, ensuring external links to legacy parity/storage management content resolve correctly.Also applies to: 554-554, 853-853, 902-902
95-126: Comprehensive remark linting configuration.The remark plugins configuration establishes consistent formatting rules for MDX documentation. The choices are sensible: space-indented lists, ATX-style headings, backtick code fences, and disabled maximum line length (appropriate for prose). The selective disabling of rules like
noShellDollarsandnoHeadingPunctuationis pragmatic for documentation that includes command-line examples and descriptive headings.
272-964: Well-organized redirect configuration.The redirects are now comprehensively organized into logical sections (Account, Category, Connect, Legacy, Unraid OS, Guides, Manual, Overview, Go links) with clear comments. The consistent formatting and extensive
/go/short-link coverage significantly improves maintainability. The standardized quote style and indentation make the configuration easier to review and modify..remarkrc.mjs (4)
1-69: LGTM! Comprehensive MDX and linting configuration.The imports and plugin configuration properly enable MDX, frontmatter, GFM, and directive support with appropriate linting rules. The explicit configuration values (bullet style, emphasis markers, list indentation, etc.) ensure consistent formatting across the documentation.
71-142: LGTM! Settings and directive handlers are well-implemented.The remark settings use explicit literals for consistency. The directive handling functions (
directiveColonSafe,wrapContainerDirectiveHandler,collapseDirectivePadding) properly manage extension modifications and state with appropriate safeguards (try/finally blocks, type checks).
144-199: Past issue fixed! Empty string preservation now works correctly.The
normalizeDirectiveFencesfunction now usesv != null(line 198) instead offilter(Boolean), which correctly preserves empty strings (legitimate blank lines) while only filtering out null/undefined values (unmatched closing fences). This directly addresses the previous review concern about collapsing required blank lines inside directives.The stack-based fence matching logic (lines 150-191) properly handles:
- Opening fences: pushed to stack with indent and colon count
- Closing fences: matched by indent, with fallback to stack pop
- Unmatched closers: returned as null and filtered out
201-231: LGTM! Robust AST traversal with proper guards.The
stripDanglingDirectiveClosingsfunction safely removes paragraph nodes containing only directive closing fences through proper validation:
- Guards verify parent, index, node type, and children structure
- Confirms the paragraph contains only a text node with closing fence pattern
- Validates the previous sibling is a containerDirective
- Returns
[SKIP, index]for correct traversal after removal
|
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
docs/unraid-os/system-administration/maintain-and-update/upgrading-unraid.mdx (1)
19-19: Consider simplifying relative paths for clarity.Both lines 19 and 142 use the relative path
../maintain-and-update/changing-the-flash-device.mdxto reference a file in the same directory. While functionally correct, this can be simplified to./changing-the-flash-device.mdxfor improved readability and maintainability.Apply this diff to simplify the relative path on line 19:
-Before you start upgrading, make sure to create a complete backup of your USB flash device. For more details, refer to [Backing up your flash device](../maintain-and-update/changing-the-flash-device.mdx#backing-up-your-flash-device). +Before you start upgrading, make sure to create a complete backup of your USB flash device. For more details, refer to [Backing up your flash device](./changing-the-flash-device.mdx#backing-up-your-flash-device).Apply the same simplification on line 142:
-Manual downgrades are only needed if you can't access the %%WebGUI|web-gui%% or if the downgrade option isn't available. Before proceeding, it's important to back up your USB flash device. For more details, see [Backing up your flash device](../maintain-and-update/changing-the-flash-device.mdx#backing-up-your-flash-device). +Manual downgrades are only needed if you can't access the %%WebGUI|web-gui%% or if the downgrade option isn't available. Before proceeding, it's important to back up your USB flash device. For more details, see [Backing up your flash device](./changing-the-flash-device.mdx#backing-up-your-flash-device).
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
docs/unraid-os/release-notes/7.2.0.md(9 hunks)docs/unraid-os/system-administration/maintain-and-update/upgrading-unraid.mdx(1 hunks)docs/unraid-os/troubleshooting/licensing-faq.mdx(6 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/unraid-os/troubleshooting/licensing-faq.mdx
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-09-17T16:28:59.403Z
Learnt from: elibosley
Repo: unraid/docs PR: 325
File: docs/unraid-os/system-administration/maintain-and-update/changing-the-flash-device.mdx:123-131
Timestamp: 2025-09-17T16:28:59.403Z
Learning: Unraid's flash backup feature (accessed via Main tab → Flash device → FLASH BACKUP) creates complete installation ZIP files that include both the Unraid OS and user configuration. These backup ZIPs are compatible with the USB Flash Creator's "Use custom" option for restoring to new flash devices.
Applied to files:
docs/unraid-os/system-administration/maintain-and-update/upgrading-unraid.mdxdocs/unraid-os/release-notes/7.2.0.md
🪛 LanguageTool
docs/unraid-os/release-notes/7.2.0.md
[style] ~173-~173: Consider using the internationally preferred transliteration for the capital of Ukraine.
Context: ...ireGuard tunnels - Improvement: Europe/Kiev timezone renamed to Europe/Kyiv to a...
(KIEV)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: deploy-preview
🔇 Additional comments (5)
docs/unraid-os/release-notes/7.2.0.md (3)
34-34: Formatting improvements enhance documentation accessibility and consistency.The reformatted navigation references using bold-italic combinations (e.g.,
**_Main → Pool Devices_**) improve visual hierarchy and readability for navigating the Unraid webGUI. The consistent application of this pattern across all UI path references supports the PR's accessibility objectives.Regarding the timezone update on line 173, the change from
_Europe/Kiev_to_Europe/Kyiv_correctly reflects the IANA Time Zone Database update and aligns with international standards.Also applies to: 37-37, 50-50, 62-62, 92-92, 138-140, 171-171, 173-173
189-195: Kernel configuration formatting is clear and scannable.The eMMC support configuration options (lines 189–195) are presented with consistent, easy-to-scan formatting that makes the feature additions immediately clear.
198-198: Package version entries maintain semantic accuracy.The formatting adjustments to package/version entries (e.g.,
aaa_glibc-solibs,ncurses,php,rclone) preserve content accuracy while improving readability within the release notes context.Also applies to: 263-263, 278-278, 280-280
docs/unraid-os/system-administration/maintain-and-update/upgrading-unraid.mdx (2)
132-152: Link verified—downgrade section is correct.The relative link to
changing-the-flash-device.mdx#backing-up-your-flash-deviceresolves correctly to the existing heading "Backing up your flash device." The restructured downgrade workflow (WebGUI option first, then manual fallback) improves clarity and user guidance. The conditional flow appropriately directs users to the correct path based on their situation.
8-11: All partial component files are present.Verification confirms all four partial files referenced in the imports exist in the
partials/subdirectory. No issues found with the import statements at lines 8-11.
- 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.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
docs/unraid-os/troubleshooting/licensing-faq.mdx (2)
81-94: Centered table with inline styles—consider CSS class extraction for consistency.The table centering approach using inline flexbox styles works functionally and improves readability. For better maintainability across the documentation, consider extracting the centering pattern to reusable CSS classes in a future refactor.
160-168: Centered table using consistent inline style pattern.The license limits table is properly centered using the same flexbox approach as the upgrade path table. As noted previously, extracting this centering pattern to reusable CSS classes would improve maintainability across the documentation.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/unraid-os/troubleshooting/licensing-faq.mdx(6 hunks)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: deploy-preview
🔇 Additional comments (3)
docs/unraid-os/troubleshooting/licensing-faq.mdx (3)
4-4: Frontmatter metadata addition improves documentation structure.The
toc_max_heading_level: 3addition appropriately controls table of contents depth and aligns with the PR objective to improve accessibility.
49-61: Iframe implementation with proper JSX attributes and accessibility.The iframe correctly uses camelCase for JSX attributes (
frameBorder,webkitAllowFullScreen,mozAllowFullScreen,allowFullScreen) and includes a descriptivetitleattribute for accessibility. The centered flexbox wrapper appropriately improves visual presentation. The past review comment regarding JSX attribute casing has been properly addressed.
212-216: Trial extension section updated with clear policy details and support links.The section now provides specific information about trial extension limits (30 days initially, extendable twice for 14 days each, total 60 days) and proper contact information via email and support portal. The content is clear and links are properly formatted.
2 participants
Before Submitting This PR, Please Ensure You Have Completed The Following:
Summary by CodeRabbit