Consolidate links to separate page

closes #7

mkdocs/docs/channels.md

@@ -13,13 +13,9 @@ Accessible at `/channel/` of your Tube Archivist, the **Overview Page** shows a
 
 The **Subscribe to Channels** button <img src="/assets/icon-add.png?raw=true" alt="add icon" width="20px" style="margin:0 5px;"> opens a text field to subscribe to a channel. You have a few options:
 
-- Enter the YouTube channel ID, a 25 character alphanumeric string. Example:
+- Enter a [channel](urls.md#channel).
-    - `UCBa659QWEk1AI4Tg--mrJ2A`
+- Enter a [video](urls.md#video) and let Tube Archivist extract the channel ID for you.
-- Enter the URL to the channel page on YouTube. Example:
+- Add one per line.
-    - `https://www.youtube.com/channel/UCBa659QWEk1AI4Tg--mrJ2A` or alias url `https://www.youtube.com/@TomScottGo`
-- Enter a channel alias starting with *@*, for example: `@TomScottGo`
-- Enter the video URL for any video and let Tube Archivist extract the channel ID for you, for example `https://www.youtube.com/watch?v=2tdiKTSdE9Y`
-- If you want to subscribe to more than one channel directly, you can add one channel per line in the text field
 
 To search your channels, click on the search icon <img src="/assets/icon-search.png?raw=true" alt="search icon" width="20px" style="margin:0 5px;"> to reach the search page. Start your query with `channel:`, learn more on the [search](search.md) page.
 

mkdocs/docs/downloads.md

@@ -27,30 +27,13 @@ The **Add to Download Queue** icon <img src="/assets/icon-add.png?raw=true" alt=
 You have a few options:
 
 ### Videos
-- Add a YouTube video ID, for example `2tdiKTSdE9Y`
+Add a [video](urls.md#video) URL to download a single video.
-- Add a link to a YouTube video, for example `https://www.youtube.com/watch?v=2tdiKTSdE9Y`
-- Add a link to a YouTube video by providing the shortened URL, for example `https://youtu.be/2tdiKTSdE9Y`
-- Add a link to a shorts video, for example `https://www.youtube.com/shorts/UOfe6e0k7cQ`
 
 ### Channels
-- When adding a channel, Tube Archivist will ignore the channel page size as described above, this is meant for an initial download of the whole channel. You can still ignore selected videos from the queue before starting the download.
+Add a [channel](urls.md#channel) to download the complete channel, or a [channel sub page](urls.md#channel-sub-pages) to download a partial channel.
-
-- Download a complete channel including shorts and streams by entering:
-    - Channel ID: `UCBa659QWEk1AI4Tg--mrJ2A`
-    - Channel URL: `https://www.youtube.com/channel/UCBa659QWEk1AI4Tg--mrJ2A`
-    - Channel `@` alias handle: For example `@TomScottGo`
-    - Channel alias URL: `https://www.youtube.com/@TomScottGo`
-
-- Download videos, live streams or shorts only, by providing a partial channel URL:  
-    - Videos only: `https://www.youtube.com/@IBRACORP/videos`
-    - Shorts only: `https://www.youtube.com/@IBRACORP/shorts`
-    - Streams only: `https://www.youtube.com/@IBRACORP/streams`
-    - Every other channel sub page will default to download all, for example `https://www.youtube.com/@IBRACORP/featured` will download videos and shorts and streams.
 
 ### Playlist
-- Add a playlist ID or URL to add every available video in the list to the download queue, for example `https://www.youtube.com/playlist?list=PL96C35uN7xGLLeET0dOWaKHkAlPsrkcha` or `PL96C35uN7xGLLeET0dOWaKHkAlPsrkcha`.
+Add a [playlist](urls.md#playlist) to download all videos in the list. When adding a playlist to the queue, this playlist will automatically get [indexed](playlists.md#playlist-detail).
-- When adding a playlist to the queue, this playlist will automatically get [indexed](playlists.md#playlist-detail).
-- When you add a link to a video in a playlist, Tube Archivist assumes you want to download only the specific video and not the whole playlist, for example `https://www.youtube.com/watch?v=CINVwWHlzTY&list=PL96C35uN7xGLLeET0dOWaKHkAlPsrkcha` will only add one video, `CINVwWHlzTY`, to the queue.
 
 ## The Download Queue
 Below the three buttons you find the download queue. New items will get added at the bottom of the queue, the next video to download once you click on **Start Download** will be the first in the list.

mkdocs/docs/playlists.md

@@ -13,11 +13,8 @@ You can index playlists of a channel from the channel detail page as described [
 
 The **Subscribe to Playlist** button <img src="/assets/icon-add.png?raw=true" alt="add icon" width="20px" style="margin:0 5px;"> opens a text field to subscribe to playlists. You have a few options:
 
-- Enter the YouTube playlist id, for example:
+- Enter a playlist [playlist](urls.md#playlist)
-    - `PL96C35uN7xGLLeET0dOWaKHkAlPsrkcha`
+- Add one per line.
-- Enter the Youtube dedicated playlist url, for example:
-    - `https://www.youtube.com/playlist?list=PL96C35uN7xGLLeET0dOWaKHkAlPsrkcha`
-- If you want to subscribe to more than one playlist directly, you can add one playlist per line in the text field
 
 !!! note
     It doesn't make sense to subscribe to a playlist if you are already subscribed the corresponding channel as this will slow down the **Rescan Subscriptions** [task](downloads.md#rescan-subscriptions).

mkdocs/docs/urls.md

@@ -0,0 +1,43 @@
+---
+description: How URLs from YouTube get parsed
+---
+
+# URLs
+This document describes how Tube Archivist identifies and treats links from YouTube.
+
+!!! note
+    Application logic of Tube Archivist is tied only to the IDs, not the names.
+
+## Video
+A video ID is **11** characters long, e.g. `2tdiKTSdE9Y`.
+
+Urls can have several forms:  
+
+- Watch URL: Regular URLs so will see while browsing YouTube, with the path */watch* and a *v* parameter, e.g. `https://www.youtube.com/watch?v=2tdiKTSdE9Y`
+- Share URL: Link you will get when you click on *share* on a video, e.g. `https://youtu.be/2tdiKTSdE9Y`
+- Shorts URL: e.g. `https://www.youtube.com/shorts/U80grnZJm_8`
+
+## Channel
+A channel ID is **24** characters long, e.g. `UCBa659QWEk1AI4Tg--mrJ2A`.
+
+Channel URLs can have these forms, all will get translated to the ID:
+
+- ID URL: With a *channel* path, e.g. `https://www.youtube.com/channel/UCBa659QWEk1AI4Tg--mrJ2A`
+- Channel Handle: Starting with a `@` this handle is personal and unique, e.g. `@TomScottGo`
+- Alias URL: Based off the channel handle, e.g. `https://www.youtube.com/@TomScottGo`
+
+### Channel sub pages
+Tube archivist can separate between different subpages:
+
+- Videos only: `https://www.youtube.com/@IBRACORP/videos`
+- Shorts only: `https://www.youtube.com/@IBRACORP/shorts`
+- Streams only: `https://www.youtube.com/@IBRACORP/streams`
+- Every other channel sub page will default to download all, for example `https://www.youtube.com/@IBRACORP/featured` will download videos and shorts and streams.
+
+## Playlist
+A playlist ID can be `34`, `26` or `18` characters long, e.g. `PL96C35uN7xGLLeET0dOWaKHkAlPsrkcha`
+
+- Playlist URLs start with a *playlist* path and has a *list* parameter, e.g. `https://www.youtube.com/playlist?list=PL96C35uN7xGLLeET0dOWaKHkAlPsrkcha`
+
+### Playlist vs Video URLs
+While browsing YouTube videos in Playlists, you might encounter URLs looking like that: `https://www.youtube.com/watch?v=QPZ0pIK_wsc&list=PL96C35uN7xGLLeET0dOWaKHkAlPsrkcha`. As established above, based on the */watch* path and the *v* parameter, Tube Archivist will treat this as a video with the ID `QPZ0pIK_wsc` and **not** as a playlist. If you mean the playlist, you can easily grab the correct ID from the URL, e.g. `PL96C35uN7xGLLeET0dOWaKHkAlPsrkcha`.

mkdocs/mkdocs.yml

@@ -4,6 +4,7 @@ nav:
     - Home: 'index.md'
     - User Guide:
         - 'FAQ': 'faq.md'
+        - 'URLs': 'urls.md'
         - 'Downloads Page': 'downloads.md'
         - 'Channels Pages': 'channels.md'
         - 'Video': 'video.md'