D3SOX · Sep 23, 2026 · Sep 23, 2026 · Sep 23, 2026
diff --git a/public/docs-images/create-playlist-dark.webp b/public/docs-images/create-playlist-dark.webp
diff --git a/public/docs-images/create-playlist-light.webp b/public/docs-images/create-playlist-light.webp
diff --git a/public/docs-images/create-profile-dark.webp b/public/docs-images/create-profile-dark.webp
diff --git a/public/docs-images/create-profile-light.webp b/public/docs-images/create-profile-light.webp
diff --git a/public/docs-images/data-dark.webp b/public/docs-images/data-dark.webp
diff --git a/public/docs-images/data-light.webp b/public/docs-images/data-light.webp
diff --git a/public/docs-images/download-settings-dark.webp b/public/docs-images/download-settings-dark.webp
diff --git a/public/docs-images/download-settings-light.webp b/public/docs-images/download-settings-light.webp
diff --git a/public/docs-images/player-dark.webp b/public/docs-images/player-dark.webp
diff --git a/public/docs-images/player-light.webp b/public/docs-images/player-light.webp
diff --git a/public/docs-images/privacy-dark.webp b/public/docs-images/privacy-dark.webp
diff --git a/public/docs-images/privacy-light.webp b/public/docs-images/privacy-light.webp
diff --git a/public/docs-images/providers-dark.webp b/public/docs-images/providers-dark.webp
diff --git a/public/docs-images/providers-light.webp b/public/docs-images/providers-light.webp
diff --git a/public/docs-images/quick-settings-dark.webp b/public/docs-images/quick-settings-dark.webp
diff --git a/public/docs-images/quick-settings-light.webp b/public/docs-images/quick-settings-light.webp
diff --git a/public/docs-images/sponsorblock-dark.webp b/public/docs-images/sponsorblock-dark.webp
diff --git a/public/docs-images/sponsorblock-light.webp b/public/docs-images/sponsorblock-light.webp
diff --git a/public/docs-images/storage-dark.webp b/public/docs-images/storage-dark.webp
diff --git a/public/docs-images/storage-light.webp b/public/docs-images/storage-light.webp
diff --git a/public/docs-images/takeout/history.png b/public/docs-images/takeout/history.png
diff --git a/public/docs-images/takeout/json.png b/public/docs-images/takeout/json.png
diff --git a/public/docs-images/takeout/youtube.png b/public/docs-images/takeout/youtube.png
diff --git a/public/docs-sources/freetube-license.txt b/public/docs-sources/freetube-license.txt
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 FreeTubeApp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/src/components/PageIndex.astro b/src/components/PageIndex.astro
@@ -1,7 +1,7 @@
 ---
 export interface IndexGroup {
 	label: string;
-	links: { label: string; href: string }[];
+	links: { label: string; href: string; current?: boolean }[];
 }
 
 interface Props {
@@ -20,13 +20,13 @@ const { label, groups, collapsibleGroups = false } = Astro.props;
 			<option value="">Choose a section</option>
 			{groups.map((group) => (
 				<optgroup label={group.label}>
-					{group.links.map((link) => <option value={link.href}>{link.label}</option>)}
+					{group.links.map((link) => <option value={link.href} selected={link.current}>{link.label}</option>)}
 				</optgroup>
 			))}
 		</select>
 	</label>
 	<div class="page-index__desktop">
-		<p class="feature-toc__label">On this page</p>
+		<p class="feature-toc__label">{label}</p>
 		<div class="feature-toc__scroll">
 			{groups.map((group) => {
 				const Group = collapsibleGroups ? 'details' : 'div';
@@ -35,7 +35,7 @@ const { label, groups, collapsibleGroups = false } = Astro.props;
 				<Group class="page-index__group" open={collapsibleGroups ? true : undefined}>
 					<Heading class="page-index__group-label">{group.label}</Heading>
 					<ol class="feature-toc__list">
-						{group.links.map((link) => <li><a href={link.href}>{link.label}</a></li>)}
+						{group.links.map((link) => <li><a href={link.href} class:list={[{ 'is-active': link.current }]} aria-current={link.current ? 'page' : undefined}>{link.label}</a></li>)}
 					</ol>
 				</Group>
 			); })}

diff --git a/src/content.config.ts b/src/content.config.ts
@@ -0,0 +1,9 @@
+import { defineCollection, z } from 'astro:content';
+import { glob } from 'astro/loaders';
+
+export const collections = {
+	guides: defineCollection({
+		loader: glob({ pattern: '**/*.md', base: './src/content/guides' }),
+		schema: z.object({ title: z.string(), description: z.string(), order: z.number() }),
+	}),
+};
diff --git a/src/content/guides/downloads.md b/src/content/guides/downloads.md
@@ -0,0 +1,51 @@
+---
+title: Downloads and offline viewing
+description: Save video or audio, manage the queue, and find your downloaded files.
+order: 5
+---
+
+## Set up downloads
+
+1. Open **Settings → Downloads** and turn on **Enable Downloads** if needed.
+2. Choose a **Download Folder** you can write to and that has enough free space.
+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>
+
+*Select the folder icon in Download Folder to choose where files are saved.*
+
+Android uses its own storage picker and download implementation. Grant access to your chosen folder when prompted; desktop executable paths and the choice of system-installed tools do not apply there.
+
+## Download a video or audio
+
+1. Open a video or its menu and select **Download Video**.
+2. In the download dialog, choose the offered format and quality, or an audio-only option when you want sound without video.
+3. Confirm the download.
+4. Open **Downloads** from the top bar or profile menu to see progress and queued items.
+
+Downloads need a working connection until they finish. Higher-quality video usually uses more storage. Subtitles can be downloaded when offered for the selected video.
+
+## Play a completed download
+
+1. Open **Downloads** and find a completed item.
+2. Choose **Play download** to watch the saved media.
+3. On desktop, use **Show in Folder** to locate the file in your file manager.
+
+Keep the file in its saved location if you want OpenTubeX to find it again. Clearing an entry from the list and permanently deleting its file are different actions; read the confirmation before removing media.
+
+## Download a playlist
+
+Open a playlist's menu and choose **Download Playlist** when available. Review the download options before starting: a large playlist can use significant space. The **Downloads** panel shows the queued work.
+
+## Manage a failed download
+
+1. Open **Downloads** and read the item's error.
+2. Check your connection, free space, and access to the download folder.
+3. On desktop, check managed tool updates under **Settings → Advanced → External Software** if the error mentions yt-dlp or FFmpeg.
+4. Use **Retry download** after fixing the cause.
+
+If the video itself will not play, start with [playback troubleshooting](/docs/troubleshooting/#a-video-will-not-play). Include the download error and platform when [reporting a bug](/docs/troubleshooting/#report-a-bug).
diff --git a/src/content/guides/getting-started.md b/src/content/guides/getting-started.md
@@ -0,0 +1,68 @@
+---
+title: Subscriptions and playlists
+description: Find videos, follow channels, and organize your local library.
+order: 2
+---
+
+## Find a video or channel
+
+1. Enter a title, channel name, or YouTube link in the search field.
+2. Submit the search and open a result.
+3. Open the channel name to browse more uploads from that creator.
+
+OpenTubeX keeps your subscriptions and local playlists in the app. You do not need to sign in to YouTube, and these changes do not update your YouTube account.
+
+## Subscribe to a channel
+
+1. Open the channel you want to follow.
+2. Select **Subscribe**.
+3. Open **Subscriptions** in the navigation to see uploads from your channels. On a small screen, some navigation entries are under **More**.
+4. Use the feed's refresh action to fetch new uploads.
+
+Already have subscriptions elsewhere? [Import your existing subscriptions](/docs/importing/#import-subscriptions) instead of adding channels one by one.
+
+## Use profiles
+
+Profiles let you group channels, for example into work and leisure viewing.
+
+1. Open the profile menu from your profile icon.
+2. Use the profile selector to choose or manage a profile.
+3. Check which profile is active when viewing your subscriptions.
+
+If a channel appears to be missing, check **All Channels** before importing it again. Feed filters can also hide videos, Shorts, or live content.
+
+For step-by-step profile creation and bulk channel management, see [Organize channels with profiles](/docs/profiles/).
+
+## Create a local playlist
+
+1. Open **Playlists** in the navigation.
+2. Select **Create New Playlist**.
+3. Enter a name and select **Create**.
+4. On a video, use **Add to Playlist** and choose the playlist. On desktop, video cards also expose actions on hover; use the video's menu when an action is not visible.
+5. Return to **Playlists** and open your playlist to watch its videos.
+
+<picture>
+  <source data-shot-theme="dark" media="(prefers-color-scheme: dark)" srcset="/docs-images/create-playlist-dark.webp" type="image/webp" />
+  <source data-shot-theme="light" media="(prefers-color-scheme: light)" srcset="/docs-images/create-playlist-light.webp" type="image/webp" />
+  <img src="/docs-images/create-playlist-light.webp" alt="New Playlist Name dialog with an example name and Create and Cancel buttons." width="632" height="210" loading="lazy" decoding="async" />
+</picture>
+
+*Give the playlist a name, then select Create. This example uses “Watch this weekend”.*
+
+Local playlists are stored by OpenTubeX. They are separate from public YouTube playlists, and adding a video does not download it. See [Downloads](/docs/downloads/) to save media for offline use.
+
+## Open settings
+
+1. Select your profile icon to open the quick settings menu.
+2. Choose **All settings**.
+3. Select a category or use settings search to find an option by name.
+
+<picture>
+  <source data-shot-theme="dark" media="(prefers-color-scheme: dark)" srcset="/docs-images/quick-settings-dark.webp" type="image/webp" />
+  <source data-shot-theme="light" media="(prefers-color-scheme: light)" srcset="/docs-images/quick-settings-light.webp" type="image/webp" />
+  <img src="/docs-images/quick-settings-light.webp" alt="OpenTubeX quick settings menu with the All settings gear in the upper-right corner." width="440" height="792" loading="lazy" decoding="async" />
+</picture>
+
+*Select the gear at the top right of quick settings to open All settings.*
+
+Start with [Playback and settings](/docs/playback/) for captions, autoplay, appearance, and SponsorBlock. [Back up your library](/docs/importing/#back-up-your-library) once you have it set up.
diff --git a/src/content/guides/google-takeout.md b/src/content/guides/google-takeout.md
@@ -0,0 +1,86 @@
+---
+title: Import from Google Takeout
+description: Move your YouTube subscriptions, watch history, and search history into OpenTubeX.
+order: 3.5
+---
+
+Google Takeout exports your Google account data. OpenTubeX imports the extracted subscription and history files; you do not need to sign in to Google inside OpenTubeX.
+
+## Choose your YouTube data
+
+1. Open [Google Takeout](https://takeout.google.com/) in your browser and sign in to the account you use for YouTube.
+2. Choose **Deselect all**, then select **YouTube and YouTube Music**.
+3. Open **All YouTube data included**. Deselect everything in that dialog, then select **subscriptions** for your channel list and **history** if you also want watch and search history.
+4. Confirm with **OK**.
+
+Selecting only these categories avoids including uploaded videos and other unrelated data. If you use more than one Google account, check which account is selected before exporting.
+
+<img src="/docs-images/takeout/history.png" alt="Google Takeout content-options dialog with history selected." width="431" height="451" loading="lazy" decoding="async" />
+
+*Select history for watch and search history. To transfer subscriptions too, scroll to the subscriptions option and select it as well.*
+
+The Google Takeout screenshots below and above come from [Positroid's September 2025 walkthrough](https://positroid.tech/en/post/youtube-history-analyzer). They show the relevant controls, but are not captures of today's interface. Google may change the layout and labels. The screenshots retain Google's original light appearance; OpenTubeX screenshots follow your selected website theme.
+
+## Choose JSON for history
+
+1. In the **YouTube and YouTube Music** entry, open **Multiple formats**.
+2. Change **History** to **JSON** and confirm with **OK**.
+3. Select **Next step**.
+
+<img src="/docs-images/takeout/json.png" alt="Google Takeout format dialog with history set to JSON." width="553" height="319" loading="lazy" decoding="async" />
+
+*Set history to JSON before requesting the export.*
+
+<img src="/docs-images/takeout/youtube.png" alt="Google Takeout YouTube entry showing JSON format, one data type selected, and the Next step button." width="689" height="409" loading="lazy" decoding="async" />
+
+*After making your choices, the buttons may read JSON format and a count of selected types rather than Multiple formats and All YouTube data included. This example includes history only.*
+
+This step matters for watch and search history. OpenTubeX expects a JSON history export, not Takeout's HTML version. Subscription exports use CSV. Renaming an HTML file to `.json` does not convert it.
+
+## Create and download the export
+
+1. Choose **Send download link via email**, **Export once**, and **.zip**.
+2. Select **Create export**.
+3. Wait for Google to prepare the archive. Use the download link when it is ready; Google may ask you to sign in again.
+4. Download the ZIP and extract it with your file manager. If Google splits the export into several archives, extract the parts containing your YouTube data.
+
+You do not need to upload the archive to another website. Creating an export does not delete your data from Google. [Google's export help](https://support.google.com/accounts/answer/3024190) covers delivery options and account-specific problems.
+
+## Find the files and import them
+
+Look inside the extracted `Takeout/YouTube and YouTube Music/` folder. Folder names may differ with your Google account language.
+
+| Data | File inside that folder | OpenTubeX action |
+| --- | --- | --- |
+| Subscriptions | `subscriptions/subscriptions.csv` | Import Subscriptions |
+| Watch history | `history/watch-history.json` | Import History |
+| Search history | `history/search-history.json` | Import search history |
+
+1. In OpenTubeX, open your profile menu, choose **All settings**, then **Data & Storage → Data**.
+2. Choose the action from the table and select its extracted file.
+3. Wait for the import result before starting another import.
+4. Check **Subscriptions** or **History** in the app. Refresh the subscription feed to fetch channel uploads.
+
+<picture>
+  <source data-shot-theme="dark" media="(prefers-color-scheme: dark)" srcset="/docs-images/data-dark.webp" type="image/webp" />
+  <source data-shot-theme="light" media="(prefers-color-scheme: light)" srcset="/docs-images/data-light.webp" type="image/webp" />
+  <img src="/docs-images/data-light.webp" alt="OpenTubeX Data & Storage settings showing the separate import actions for subscriptions, history, and search history." width="1232" height="820" loading="lazy" decoding="async" />
+</picture>
+
+*Select the import action for each extracted file. The ZIP itself is not the file to select.*
+
+## If something is missing
+
+- **Only HTML history files:** create another export with History set to JSON.
+- **No subscriptions or history folder:** check the account and the selected data categories. The archive's `archive_browser.html` is an index, not a history file.
+- **Older history is missing:** the export can only contain data Google still retains. Previously deleted activity may not be recoverable.
+- **A channel is missing after import:** check the import result and your active [profile](/docs/profiles/). A removed channel or incomplete export may need investigation.
+- **You want to import playlists:** OpenTubeX's playlist importer accepts OpenTubeX / FreeTube `.db` exports, not Takeout playlist files.
+
+Keep your original archive until you have checked the imported data. See [Importing and backing up data](/docs/importing/) for other supported formats.
+
+## Sources and image credits
+
+Takeout instructions are adapted from FreeTube's [subscription](https://docs.freetubeapp.io/usage/importing-subscriptions/) and [history](https://docs.freetubeapp.io/usage/importing-history/) guides, with OpenTubeX-specific import steps. General export behavior is checked against [Google Account Help](https://support.google.com/accounts/answer/3024190).
+
+The three Google Takeout UI screenshots are reproduced unchanged from [positron48's source images](https://github.com/positron48/youtube-history-analyzer/tree/master/images), published with the September 2025 article linked above. Google product visuals belong to Google and are shown for instructional purposes; they are not covered by FreeTube's MIT license. See [Google's educational-use guidance](https://about.google/brand-resource-center/guidance/). OpenTubeX is not affiliated with Google.
diff --git a/src/content/guides/importing.md b/src/content/guides/importing.md
@@ -0,0 +1,58 @@
+---
+title: Importing and backing up data
+description: Bring subscriptions and history with you, and save a copy of your library.
+order: 3
+---
+
+## Find the import and export controls
+
+1. Open your profile menu and select **All settings**.
+2. Select **Data & Storage**.
+3. Open the **Data** tab. Each data type has its own import and export action.
+
+<picture>
+  <source data-shot-theme="dark" media="(prefers-color-scheme: dark)" srcset="/docs-images/data-dark.webp" type="image/webp" />
+  <source data-shot-theme="light" media="(prefers-color-scheme: light)" srcset="/docs-images/data-light.webp" type="image/webp" />
+  <img src="/docs-images/data-light.webp" alt="Data & Storage settings with separate import and export buttons for subscriptions, history, playlists, search history, and settings." width="1232" height="820" loading="lazy" decoding="async" />
+</picture>
+
+*Desktop Data & Storage settings. Choose the action for the type of data you are moving.*
+
+## Import subscriptions
+
+1. Export subscriptions from your previous app. For YouTube, request a YouTube data export through [Google Takeout](https://takeout.google.com/), including subscriptions.
+2. Extract any downloaded archive first. You need the subscriptions file inside it, not the ZIP archive.
+3. In OpenTubeX, select **Import Subscriptions** in the Data tab and choose the file.
+4. Wait for the import result. Open **Subscriptions**, check the active profile, and refresh the feed.
+
+Supported subscription formats include OpenTubeX / FreeTube **.db**, YouTube Takeout **.csv**, **.json**, or **.opml**, NewPipe **.json**, and LibreTube backup or FreeTube export **.json**. A JSON file must contain the expected export data; renaming a different file does not convert it.
+
+### Get your subscriptions from YouTube
+
+Follow the [Google Takeout walkthrough](/docs/google-takeout/) to export subscriptions as CSV and watch/search history as JSON. It covers export selection, the history format, and exactly which extracted file to import.
+
+### Move from another app
+
+Export a subscription file from your previous app, then transfer it to the device running OpenTubeX. Use a subscriptions export rather than a full archive when your app offers both. For OpenTubeX or FreeTube, keep the original .db file; for NewPipe, use its subscriptions .json export. Import the file with the steps above.
+
+## Import history or playlists
+
+1. In the Data tab, choose **Import History**, **Import Playlists**, or **Import search history**.
+2. Select the matching exported file and wait for the result.
+3. Open the corresponding library page to check the imported entries.
+
+**History** accepts OpenTubeX / FreeTube .db, YouTube Takeout .json, and LibreTube backup .json. **Search history** accepts OpenTubeX / FreeTube .db and YouTube Takeout .json. **Playlists** accepts OpenTubeX / FreeTube .db exports; the playlist importer does not accept a YouTube Takeout archive.
+
+## Back up your library
+
+1. Open **Settings → Data & Storage → Data**.
+2. Select **Export Subscriptions**, then **Export OpenTubeX** to keep OpenTubeX profiles and subscriptions.
+3. Export **History**, **Playlists**, **search history**, and **Settings** separately if you want to keep those too.
+4. Save the files in a backup location you can find on your other device.
+5. To restore, use the matching import actions on that device.
+
+Exports contain your personal viewing data. Store them privately. Settings exports omit device-specific and experimental options, such as proxy configuration, external-player paths, and screenshot folders. Downloaded video and audio files are separate from these exports; copy those files separately if you need them.
+
+## If an import fails
+
+Check the file type against the supported formats above, extract archives, and make sure you selected the correct data action. Keep the original export unchanged. If an import reports skipped items, inspect the result before assuming everything transferred. See [Troubleshooting](/docs/troubleshooting/#imports-or-subscriptions-look-incomplete) for the next steps.