refactor: restructure docs with customization, cli, and development sections #190
Conversation
…ections - Reorganize 'advanced-usage' into focused 'customization' and 'cli' sections - Add Linux-specific setup and legacy versions to Getting Started - Remove duplicate CLI installation page - Add development/extensions.md guide - Move uninstallation to top-level page - Remove undocumented exit codes table and legacy extensions
Deploying spicetify-docs with
|
| Latest commit: |
3780d01
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://9ec7c432.spicetify-docs.pages.dev |
| Branch Preview URL: | https://spicetify-docs-review.spicetify-docs.pages.dev |
|
Caution Review failedThe pull request is closed. WalkthroughThis PR reorganizes documentation: removes legacy Changes
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes
Possibly related PRs
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
📜 Recent review detailsConfiguration used: Organization UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (1)
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: 2
🧹 Nitpick comments (4)
docs/uninstallation.md (1)
93-99: Harden the Linux/macOS binary removal exampleTo avoid issues with unusual paths or empty
whichoutput, consider a slightly safer example:which spicetify # Then, for the path shown: sudo rm "$(command -v spicetify)"This keeps the intent but adds quoting and makes it clearer that elevated permissions may be needed.
docs/customization/index.md (1)
1-48: Strong central overview for the new Customization sectionThe breakdown of themes/extensions/custom apps plus Marketplace vs manual flows is clear and matches the new docs structure. The config section and link to the Configuration Reference round it out well; optionally, you could also add a small link to the CLI Reference for users who want more detail on
spicetify config, but it’s not required.docs/customization/themes.md (1)
84-91: Consider adding a note about checking theme compatibility.The "Unmaintained" section helpfully warns users about potentially broken themes. Consider adding guidance on how users can check if a theme is compatible with their Spotify version before installing, or suggest checking the theme's GitHub issues page for compatibility reports.
docs/development/extensions.md (1)
130-141: API request examples should note async context requirement.The
awaitkeyword is used but the code snippet doesn't show it wrapped in an async function. New developers might be confused about where this code should be placed.Consider adding context or wrapping in an async function:
### Making API Requests ```js +async function fetchPlayerState() { // GET request const response = await Spicetify.CosmosAsync.get( "https://api.spotify.com/v1/me/player" ); // POST request await Spicetify.CosmosAsync.post( "https://api.spotify.com/v1/me/player/play", { uris: ["spotify:track:..."] } ); +}</blockquote></details> </blockquote></details> <details> <summary>📜 Review details</summary> **Configuration used**: CodeRabbit UI **Review profile**: CHILL **Plan**: Pro <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 4dc62e1b5b44cf95a8254ee3c691099962e5f35e and c31f2c3b38cdffa07d287233ec725fc230118ffe. </details> <details> <summary>📒 Files selected for processing (21)</summary> * `docs/advanced-usage/command-line-interface.md` (0 hunks) * `docs/advanced-usage/custom-apps.md` (0 hunks) * `docs/advanced-usage/extensions.md` (0 hunks) * `docs/advanced-usage/index.md` (0 hunks) * `docs/advanced-usage/installation.md` (0 hunks) * `docs/advanced-usage/themes.md` (0 hunks) * `docs/advanced-usage/uninstallation.md` (0 hunks) * `docs/cli/commands.md` (1 hunks) * `docs/cli/index.md` (1 hunks) * `docs/customization/config-file.md` (1 hunks) * `docs/customization/custom-apps.md` (1 hunks) * `docs/customization/extensions.md` (1 hunks) * `docs/customization/index.md` (1 hunks) * `docs/customization/marketplace.md` (1 hunks) * `docs/customization/themes.md` (1 hunks) * `docs/development/custom-apps.md` (1 hunks) * `docs/development/extensions.md` (1 hunks) * `docs/getting-started.md` (1 hunks) * `docs/uninstallation.md` (1 hunks) * `docusaurus.config.js` (1 hunks) * `sidebars.js` (2 hunks) </details> <details> <summary>💤 Files with no reviewable changes (7)</summary> * docs/advanced-usage/custom-apps.md * docs/advanced-usage/extensions.md * docs/advanced-usage/themes.md * docs/advanced-usage/index.md * docs/advanced-usage/uninstallation.md * docs/advanced-usage/installation.md * docs/advanced-usage/command-line-interface.md </details> <details> <summary>🧰 Additional context used</summary> <details> <summary>🪛 LanguageTool</summary> <details> <summary>docs/customization/config-file.md</summary> [grammar] ~88-~88: Ensure spelling is correct Context: ...` | ### [AdditionalOptions] Theme and addon configuration. | Key | Description | E... (QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1) </details> </details> </details> <details> <summary>⏰ 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)</summary> * GitHub Check: Cloudflare Pages </details> <details> <summary>🔇 Additional comments (15)</summary><blockquote> <details> <summary>docs/customization/extensions.md (1)</summary><blockquote> `1-245`: **Extensions overview and workflows look consistent and clear** The install/remove flows, config examples, and built‑in extension sections are coherent and align with the new CLI/config docs and Marketplace references. I don’t see issues that would block merging here. </blockquote></details> <details> <summary>docusaurus.config.js (1)</summary><blockquote> `98-110`: **Footer doc link rename aligns with new Customization section** Updating the footer item to label “Customization” and point to `/docs/customization` matches the new customization index and overall reorg. </blockquote></details> <details> <summary>docs/development/custom-apps.md (1)</summary><blockquote> `8-8`: **Custom Apps doc link points to the correct new location** The updated link to `/docs/customization/custom-apps` matches the new customization structure and keeps this guide in sync. </blockquote></details> <details> <summary>docs/cli/index.md (1)</summary><blockquote> `1-36`: **Concise CLI entry point looks good** The Quick Start and Getting Help sections provide a clear on‑ramp to the CLI without duplicating the detailed commands page. No issues from my side. </blockquote></details> <details> <summary>docs/cli/commands.md (1)</summary><blockquote> `1-278`: **Documentation is accurate; all commands and flags verified.** The CLI reference is well-structured and comprehensive. Web search against current spicetify CLI (v2.42.5) confirms all documented commands and flags are accurate: - Core commands (backup, apply, restore, update, upgrade) ✓ - Configuration commands (config, config-dir) ✓ - Utility commands (enable-devtools, watch, path, auto) ✓ - All flags (--help, --version, --no-restart, --quiet, --extension) ✓ Examples and workflows follow standard CLI patterns. No corrections needed. </blockquote></details> <details> <summary>docs/customization/marketplace.md (1)</summary><blockquote> `1-92`: **Well-structured Marketplace documentation.** The documentation is clear, well-organized, and provides comprehensive coverage of the Marketplace feature. The tabbed installation instructions, comparison table, and troubleshooting sections are helpful for users. </blockquote></details> <details> <summary>docs/customization/custom-apps.md (1)</summary><blockquote> `1-158`: **Comprehensive Custom Apps documentation.** The documentation covers installation methods, built-in apps with examples, and troubleshooting effectively. The cross-references to development guides and the config editing section provide good flexibility for different user skill levels. </blockquote></details> <details> <summary>docs/customization/themes.md (1)</summary><blockquote> `1-146`: **Well-organized Themes documentation.** The documentation provides clear installation paths, a curated list of community themes, and practical troubleshooting guidance. The color.ini example is a nice touch for users interested in creating themes. </blockquote></details> <details> <summary>docs/development/extensions.md (2)</summary><blockquote> `21-34`: **Minimal extension example is clear and functional.** The IIFE pattern with retry logic for waiting on Spicetify readiness is a standard approach. The example effectively demonstrates the core pattern new developers need. --- `220-249`: **Best practices section provides valuable guidance.** The performance, error handling, compatibility, and naming sections cover the key concerns for extension developers. The feature detection pattern at lines 246-248 is particularly important for handling API changes between Spotify versions. </blockquote></details> <details> <summary>sidebars.js (2)</summary><blockquote> `18-42`: **Navigation structure is well-organized.** The reorganization from "Advanced Usage" to "Customization" with focused sub-pages (marketplace, themes, extensions, custom-apps, config-file) improves discoverability. The new CLI Reference category provides clear separation of concerns. --- `283-285`: **Good placement for FAQ and Uninstallation at top level.** Moving FAQ and Uninstallation to top-level items makes them easily accessible. These are common user needs that benefit from high visibility in the navigation. </blockquote></details> <details> <summary>docs/getting-started.md (3)</summary><blockquote> `208-227`: **Marketplace section structure is clear and well-positioned.** The new Marketplace section is consistently formatted with tabbed installation instructions and clearly introduced. It appropriately follows Installation and precedes Basic Usage, creating a logical flow for users to set up the core tool first, then customize it. --- `231-250`: **Simplified Basic Usage and Updating sections align with consolidation goals.** The reduction of Basic Usage to a brief introduction and the clear Updating troubleshooting flow are appropriate given the larger reorganization. The two-step recovery (first `spicetify backup apply`, then `spicetify upgrade`) is logically presented, assuming these commands are documented in the new CLI reference section. Please confirm that `docs/cli/commands.md` documents both `spicetify backup apply` and `spicetify upgrade` so users can follow up if needed. --- `235-247`: No changes required. Both commands are correctly documented in the official CLI documentation (`docs/cli/commands.md`): - `spicetify backup apply` is the documented command for re-applying Spicetify after a Spotify update (also confirmed in `docs/faq.md`) - `spicetify upgrade` is the documented command for upgrading Spicetify itself The commands shown in the Updating section match the official CLI and are accurate. </blockquote></details> </blockquote></details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
docs/getting-started.md (1)
108-110: Resolve tilde inconsistency in Flatpak documentation (duplicate of past review).The warning at line 109 states "Do not use
~", but this contradicts lines 152–153 (showing~/.local/share/flatpak/...as a common location) and lines 165–166 (using~in shell commands). Line 169 correctly uses the absolute path for the config value.Clarify the intent by reword the warning to explicitly state: "When setting the
prefs_pathconfig, use the full absolute path—do not use~(e.g.,/home/username/...). In shell commands above,~is acceptable and will expand automatically."Also applies to: 152-153, 165-169
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (5)
docs/customization/marketplace.md(1 hunks)docs/development/custom-apps.md(1 hunks)docs/development/extensions.md(1 hunks)docs/development/themes.md(1 hunks)docs/getting-started.md(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/customization/marketplace.md
🧰 Additional context used
🪛 markdownlint-cli2 (0.18.1)
docs/development/themes.md
8-8: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
⏰ 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: Cloudflare Pages
🔇 Additional comments (6)
docs/development/custom-apps.md (2)
137-137: Verify link path for themes documentation.Line 137 references
/docs/development/themes, but the PR restructures themes into/docs/customization/themes(per the PR objectives: "reorganize 'advanced-usage' into newdocs/customization/(themes, extensions, custom apps, marketplace)"). Ensure this link points to the correct location.
6-26: Improved documentation structure with clear progression.The addition of the "App Structure" section (lines 6–19) followed by "How to Start" provides excellent clarity—showing the folder layout upfront before diving into implementation details. The updated link on line 22 to
/docs/customization/custom-appscorrectly reflects the PR's reorganization of advanced-usage content.docs/development/extensions.md (1)
1-285: Well-structured and comprehensive extension development guide.This documentation provides clear, practical guidance for developing Spicetify extensions, with excellent progression from basics to advanced patterns. The code examples are accurate and the cross-references to related documentation (API Wrapper, Spicetify Creator) are well-integrated.
docs/getting-started.md (3)
8-9: Component imports are correct.The Tabs and TabItem imports properly support the refactored tabbed interface throughout the document.
15-204: Tabbed installation structure is well-organized and user-friendly.The refactored tabbed interface effectively presents multiple installation options across platforms while keeping the document readable. Default recommendations are clearly marked, and collapsible sections handle platform-specific complexities without overwhelming users.
216-281: Marketplace, updating, and legacy sections are clear and properly structured.The Marketplace tab-based installation, simplified update guidance, and legacy version handling all effectively support users across different needs and Spotify versions.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
docs/development/extensions.md (1)
58-59: Add platform-specific DevTools shortcuts.The DevTools shortcut varies by platform. Currently only the Windows shortcut (
Ctrl+Shift+I) is shown. Consider adding macOS (Cmd+Option+I) and Linux (Ctrl+Shift+I) variants for clarity, since the guide already differentiates across platforms (e.g., file paths).- 3. Open DevTools in Spotify (<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>I</kbd>) to see console output + 3. Open DevTools in Spotify to see console output: + - **Windows/Linux**: <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>I</kbd> + - **macOS**: <kbd>Cmd</kbd> + <kbd>Option</kbd> + <kbd>I</kbd>
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (5)
docs/customization/config-file.md(1 hunks)docs/development/custom-apps.md(1 hunks)docs/development/extensions.md(1 hunks)docs/development/themes.md(1 hunks)docs/getting-started.md(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (3)
- docs/development/custom-apps.md
- docs/development/themes.md
- docs/customization/config-file.md
⏰ 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: Cloudflare Pages
🔇 Additional comments (8)
docs/getting-started.md (2)
108-110: ✅ Tilde inconsistency resolved with clear clarification.The warning at lines 108–110 now explicitly distinguishes when
~is acceptable: "The~shortcut works in shell commands but not in config values." This resolves the prior conflict nicely. Examples are consistent:
- Lines 165–166:
~used in shelllscommands ✓- Line 169: Absolute path used in config command ✓
- Lines 152–153:
~shown in informational "Common locations" (acceptable given the clarified warning) ✓Also applies to: 152-153, 165-166, 169-169
268-270: The PowerShell installation command is correct. The$v="1.2.1"variable is accessible to the pipedInvoke-Expressionbecause Invoke-Expression runs in the current scope without creating a separate scope boundary. This pattern is officially documented in the Spicetify documentation and the install.ps1 script validates the$vvariable directly.docs/development/extensions.md (6)
33-46: LGTM! Minimal extension example is clear and idiomatic.The IIFE pattern with readiness checking is a solid pattern for Spicetify extensions. The example clearly shows the poll-and-retry approach needed before accessing global Spicetify APIs.
66-78: LGTM! API reference table is well-scoped.The table clearly highlights the key namespaces needed for most extension use cases, with appropriate reference to the full API documentation. The progression from basic (Player, Platform) to advanced (ContextMenu, Modals) is logical.
232-262: LGTM! Best practices are comprehensive and well-motivated.The section covers critical concerns (performance, error handling, compatibility) with concrete examples. The emphasis on feature detection and localStorage namespacing shows understanding of real extension-development challenges.
1-20: LGTM! Documentation structure and introduction are clear.The progressive structure—from extension basics through minimal example, testing, API fundamentals, patterns, and best practices—provides a solid learning path. The opening clearly positions extensions as JavaScript files with broad capabilities.
270-284: LGTM! Publishing and resources sections provide good next steps.The guidance to publish via GitHub and the Marketplace is clear and actionable. The resources section appropriately directs readers to the full API documentation, tooling, and community examples for deeper learning.
Summary
The new
docs/development/extensions.mdfile is well-structured, comprehensive, and provides a solid learning path for extension developers. The documentation progresses logically from foundational concepts through practical examples to best practices and publishing guidance.Key strengths:
- Clear, progressive structure that takes developers from zero to productive
- Practical code examples for common patterns (events, API requests, UI, storage, notifications)
- Solid best practices section addressing real extension-development challenges
- Good pedagogical flow: minimal example → testing → reference → patterns → advanced topics
Items requiring verification:
- The referenced documentation pages (
/docs/development/spicetify-creatorand/docs/development/api-wrapper) must exist, as the file links to them in multiple places.- The DevTools shortcut could be enhanced with platform-specific variants (macOS uses
Cmd+Option+I), consistent with how the guide already differentiates across platforms for file paths.No critical errors were found. The documentation is ready for publication once the internal link destinations are confirmed.
18-18: Internal documentation links are valid. Both/docs/development/spicetify-creatorand/docs/development/api-wrapperdirectories exist with proper content.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
docs/getting-started.md (1)
108-110: Minor clarification suggested for Flatpak location examples.The warning at line 109 is now clear that
~works in shell commands but not config values. However, line 153 presents~/.local/share/flatpak/...under "Common locations" without context. Consider adding a clarifying note (e.g., "Example:~/.local/share/...would expand to/home/username/.local/share/...") to avoid confusion for users copying this path directly into config.Also applies to: 152-153
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/getting-started.md(1 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: Cloudflare Pages
🔇 Additional comments (4)
docs/getting-started.md (4)
8-9: LGTM!The Tabs component imports are appropriate for the tabbed UI pattern used throughout the installation sections.
15-55: LGTM!The tabbed installation sections are well-structured and consistently formatted across all platforms. Clear default recommendations and helpful platform-specific setup options.
Also applies to: 59-81, 181-204
220-235: LGTM!The Marketplace tabbed installation is clean and consistent with the rest of the document structure.
267-291: LGTM!The Legacy Versions section is properly structured with clear platform-specific commands and helpful resource links.
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/getting-started.md(1 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: Cloudflare Pages
🔇 Additional comments (2)
docs/getting-started.md (2)
112-114: Tilde usage is now clearly documented.The warning at lines 112–114 effectively clarifies that
~is acceptable in shell commands but must be replaced with absolute paths in config values. The examples follow this guidance: lines 169–170 use~in shelllscommands, and line 173 correctly uses the absolute path in the config value. Line 157 presents~as an informational example of common locations, which is acceptable. This resolves the prior tilde inconsistency concern.Also applies to: 157-157, 169-170, 173-173
1-295: Tabbed structure and organization are well-executed.The conversion to a tabbed UI for platform-specific installation methods (Windows, Linux, macOS) and sub-methods (e.g., PowerShell, Winget, Scoop, Homebrew, AUR) improves discoverability and reduces redundancy. The collapsible Linux-specific setup sections (Snap, Flatpak, AUR) are logically grouped and progressively disclosed, which is good UX. Path configurations are properly documented with appropriate warnings about absolute paths.
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/getting-started.md(1 hunks)
🔇 Additional comments (7)
docs/getting-started.md (7)
15-62: Windows installation section is well-organized.The tabbed layout with four package managers is clear, the PowerShell script is the sensible default, and the Scoop-specific setup in the collapsible section provides necessary guidance without cluttering the main flow.
66-88: Linux installation tabs follow good structure.Three primary methods with Shell Script as the sensible default. The commands are current and clearly presented.
90-186: Tilde inconsistency resolved through clarification.Line 116 now explicitly states that
~works in shell commands but must not be used in config values. The code follows this rule consistently: shell commands at lines 172–173 use~, while the config command at line 176 uses the full absolute path. The common locations reference at line 160 is appropriately informational context. This is a sound resolution.
188-211: macOS installation section is solid.Two methods with Shell Script as default, and Homebrew includes the necessary Spotify path configuration. Structure is consistent with other platforms.
215-219: Before First Run tip is appropriate and clear.
223-242: Marketplace installation tabs are clean and well-placed.The tabbed approach mirrors the main installation section and provides clear commands for both Windows and Unix-like platforms.
274-298: Legacy Versions section provides appropriate fallback guidance.The tabbed structure for legacy version installation is consistent with the rest of the document, and the resource links are helpful for users on older versions.
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/getting-started.md(1 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: Cloudflare Pages
🔇 Additional comments (2)
docs/getting-started.md (2)
8-211: Well-structured multi-platform installation with clear clarification on tilde usage.The tabbed UI effectively consolidates platform-specific instructions, and the clarifying warning at lines 115–117 now resolves the previous tilde inconsistency by explicitly stating that
~is acceptable in shell commands but not in config values. The examples at lines 160, 172–173 correctly use~in shell contexts without violating the rule.
278-294: No changes needed. The Windows legacy installation command correctly uses the$vvariable, which is accessible to the install.ps1 script when executed viaInvoke-Expression. The syntax matches official Spicetify documentation.
Summary
Changes
docs/customization/(themes, extensions, custom apps, marketplace),docs/cli/(commands),docs/development/extensions.mddocs/getting-started.mdwith all installation methods and platform-specific setup in collapsible sectionsSummary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.