Skip to content

feat: add illustrated user guides and Google Takeout walkthrough - #87

Merged
D3SOX merged 2 commits into
masterfrom
add-user-documentation
Sep 23, 2026
Merged

D3SOX merged 2 commits into
masterfrom
add-user-documentation

Conversation

@D3SOX

@D3SOX D3SOX commented Sep 23, 2026 •

Copy link
Copy Markdown
Member

Users need setup instructions and help with everyday tasks beyond the website’s feature overview. Add a Docs section with 12 linked guides, step-by-step instructions, and screenshots.

  • Cover installation and updates, subscriptions and playlists, profiles, imports and backups, Google Takeout, playback, downloads, SponsorBlock, providers, privacy, storage, and troubleshooting.
  • Match the existing Features/Changelog navigation, including the mobile topic selector. App screenshots follow the website’s light/dark theme and open in the existing fullscreen viewer.
  • Include dated Google Takeout screenshots with source credits and retain the FreeTube source license in the repository.

Resolves #82. Follow-up documentation maintenance rule: OpenTubeX/OpenTubeX#1507.

Validation: 21 tests passed; offline production build passed after rebasing onto the Starlight cleanup. Browser checks covered all 12 guides, 243 internal links, three viewport widths, image loading/fullscreen, theme switching, and mobile navigation.

User guide with instructions and a matching app screenshot

Implemented with GPT-6 in the Codex harness.

Review in cubic

@coderabbitai

coderabbitai Bot commented Sep 23, 2026 •

Copy link
Copy Markdown

Review in Change Stack →

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 90370613-4820-413e-a031-7bddb5ee0f4f

📥 Commits

Reviewing files that changed from the base of the PR and between 8eca5d5 and 90c97e6.

⛔ Files ignored due to path filters (3)
  • public/docs-images/takeout/history.png is excluded by !**/*.png
  • public/docs-images/takeout/json.png is excluded by !**/*.png
  • public/docs-images/takeout/youtube.png is excluded by !**/*.png
📒 Files selected for processing (41)
  • public/docs-images/create-playlist-dark.webp
  • public/docs-images/create-playlist-light.webp
  • public/docs-images/create-profile-dark.webp
  • public/docs-images/create-profile-light.webp
  • public/docs-images/data-dark.webp
  • public/docs-images/data-light.webp
  • public/docs-images/download-settings-dark.webp
  • public/docs-images/download-settings-light.webp
  • public/docs-images/player-dark.webp
  • public/docs-images/player-light.webp
  • public/docs-images/privacy-dark.webp
  • public/docs-images/privacy-light.webp
  • public/docs-images/providers-dark.webp
  • public/docs-images/providers-light.webp
  • public/docs-images/quick-settings-dark.webp
  • public/docs-images/quick-settings-light.webp
  • public/docs-images/sponsorblock-dark.webp
  • public/docs-images/sponsorblock-light.webp
  • public/docs-images/storage-dark.webp
  • public/docs-images/storage-light.webp
  • public/docs-sources/freetube-license.txt
  • src/components/PageIndex.astro
  • src/content.config.ts
  • src/content/guides/downloads.md
  • src/content/guides/getting-started.md
  • src/content/guides/google-takeout.md
  • src/content/guides/importing.md
  • src/content/guides/installing.md
  • src/content/guides/playback.md
  • src/content/guides/privacy.md
  • src/content/guides/profiles.md
  • src/content/guides/providers.md
  • src/content/guides/sponsorblock.md
  • src/content/guides/storage.md
  • src/content/guides/troubleshooting.md
  • src/layouts/DocsLayout.astro
  • src/layouts/SignalLayout.astro
  • src/pages/docs/[...id].astro
  • src/pages/docs/index.astro
  • src/scripts/jump-select.ts
  • src/styles/docs.css

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.


📝 Walkthrough

Walkthrough

The change adds a documentation section to the website, with an index, individual guides, site navigation, and styling. The guides cover installation, everyday features, library management, privacy, providers, add-ons, and troubleshooting. The change also adds an MIT License text file.

Changes

Website documentation

Layer / File(s) Summary
Guide collection, routing, and layout
src/content.config.ts, src/pages/docs/*, src/layouts/DocsLayout.astro, src/components/PageIndex.astro, src/layouts/SignalLayout.astro, src/scripts/jump-select.ts, src/styles/docs.css
The site defines a validated guide collection, renders the guide index and detail pages, adds Docs navigation, and styles the documentation layout and page index.
Installation and everyday use
src/content/guides/installing.md, src/content/guides/getting-started.md, src/content/guides/playback.md, src/content/guides/downloads.md
These guides describe installation and updates, getting started, playback settings, and downloading media.
Library, data, and privacy guides
src/content/guides/profiles.md, src/content/guides/importing.md, src/content/guides/google-takeout.md, src/content/guides/storage.md, src/content/guides/privacy.md
These guides cover profiles, data import and backup, Google Takeout, storage, and privacy settings and network behavior.
Providers, add-ons, and troubleshooting
src/content/guides/providers.md, src/content/guides/sponsorblock.md, src/content/guides/troubleshooting.md
These guides describe provider options, SponsorBlock and other add-ons, and troubleshooting steps.

License text

Layer / File(s) Summary
MIT License text
public/docs-sources/freetube-license.txt
The file adds the MIT License text for FreeTubeApp.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Other

Merge Risk: ⚪ Minimal · up to 90c97

The documentation change is mergeable after normal checks; no actionable issue remains identified.

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Linked Issues check ✅ Passed The PR meets issue #82. The installation guide covers updates and supported platform differences. The getting-started, profiles, Google Takeout, and importing guides cover subscriptions, playlists, an…
Out of Scope Changes check ✅ Passed The changes support issue #82. The Docs layout, guide collection, dynamic routes, PageIndex updates, navigation handling, and styles implement and present the documentation section. The FreeTube licen…
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 2…
Title check ✅ Passed The title clearly summarizes the main change by highlighting the illustrated user guides and Google Takeout walkthrough.
Description check ✅ Passed The description explains the Docs section, guide topics, screenshots, navigation, and reported validation. It is directly related to the changeset.
✨ Finishing Touches
📝 Generate docstrings
  • Commit to this branch
  • Create a new PR
🧪 Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR

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.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey - I've found 2 issues

Prompt for AI Agents
Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="src/content/guides/downloads.md" line_range="14-16" />
<code_context>
+3. On desktop, allow time for any required managed tools to download. OpenTubeX uses yt-dlp and FFmpeg for download tasks; tool options depend on your platform.
+
+<picture>
+  <source data-shot-theme="dark" media="(prefers-color-scheme: dark)" srcset="/docs-images/download-settings-dark.webp" type="image/webp" />
+  <source data-shot-theme="light" media="(prefers-color-scheme: light)" srcset="/docs-images/download-settings-light.webp" type="image/webp" />
+  <img src="/docs-images/download-settings-light.webp" alt="Downloads settings showing Enable Downloads, Download Folder, concurrent downloads, and bandwidth limit." width="1232" height="820" loading="lazy" decoding="async" />
+</picture>
+
</code_context>
<issue_to_address>
**issue (broader_impact):** The guides reference `/docs-images/...` assets, but no files under `public/docs-images` are added by this diff. Every illustrated OpenTubeX screenshot therefore requests a missing URL and renders as a broken image.

**Suggested fix:** Add the referenced image files under `public/docs-images` (including both theme variants and the Takeout images), or update the paths to the location where those assets are actually committed.
</issue_to_address>

### Comment 2
<location path="src/content/guides/downloads.md" line_range="14-15" />
<code_context>
+3. On desktop, allow time for any required managed tools to download. OpenTubeX uses yt-dlp and FFmpeg for download tasks; tool options depend on your platform.
+
+<picture>
+  <source data-shot-theme="dark" media="(prefers-color-scheme: dark)" srcset="/docs-images/download-settings-dark.webp" type="image/webp" />
+  <source data-shot-theme="light" media="(prefers-color-scheme: light)" srcset="/docs-images/download-settings-light.webp" type="image/webp" />
+  <img src="/docs-images/download-settings-light.webp" alt="Downloads settings showing Enable Downloads, Download Folder, concurrent downloads, and bandwidth limit." width="1232" height="820" loading="lazy" decoding="async" />
+</picture>
</code_context>
<issue_to_address>
**issue (bug_risk):** The screenshot variant is selected with `prefers-color-scheme`, which follows the operating-system preference rather than OpenTubeX's selected website theme. Choosing Dark or Light in the site's theme control while the OS uses the opposite theme leaves the guides showing the wrong screenshot variant.

**Triggers:** When the user explicitly selects a theme that differs from the operating-system color scheme.

**Suggested fix:** Drive the picture source selection from the same `data-theme`/theme state used by the site, updating the active source when the theme selector changes instead of relying only on `prefers-color-scheme`.
</issue_to_address>

Sourcery assessment

Approval pending. 2 findings to address first.

Blocking findings: src/content/guides/downloads.md:16, src/content/guides/downloads.md:15


Sourcery is free for open source - if you like our reviews please consider sharing them ✨

Comment thread src/content/guides/downloads.md
Comment thread src/content/guides/downloads.md

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 44 files

Reply with feedback, questions, or to request a fix.

Re-trigger cubic

Comment thread public/docs-sources/freetube-license.txt
Comment thread public/docs-sources/freetube-license.txt
Comment thread src/pages/docs/index.astro Outdated
Comment thread src/styles/docs.css Outdated
Comment thread src/scripts/jump-select.ts
@D3SOX

D3SOX commented Sep 23, 2026

Copy link
Copy Markdown
Member Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Sep 23, 2026 •

Copy link
Copy Markdown
✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@D3SOX
D3SOX merged commit f7f1cb1 into master Sep 23, 2026
4 checks passed
@D3SOX
D3SOX deleted the add-user-documentation branch September 23, 2026 08:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add user documentation to the website

1 participant