docs: bring YouTube page up to date

Update the YouTube documentation page, as it is seriously outdated and
thus inaccurate.

List the supported URLs YAGPDB attempts to extract the channel from;
add a separate header for the configuration options and explain how to
edit an already existing feed.

Detail the limit of 10 (250) active feeds and the behaviour when
exceeding that limit.

Explain the custom announcement message, listing additional context data
available therein, as well as outline the "danger" that arises regarding
role / everyone mentions when using it.

Signed-off-by: Luca Zeuch <[email protected]>

Author: l-zeuch

content/docs/notifications/youtube-edit-feed.png

@@ -6,33 +6,126 @@ description = "Subscribe to your favorite YouTubers without polluting your own f
 
 Get notifications from your favorite YouTubers directly in your Discord server.
 
-<!--more-->
+{{< callout context="note" title="Note: Required Bot Permissions" icon="outline/info-circle" >}}
 
-## YouTube Feed
+The bot requires at least the "Read Messages" and "Send Messages" permissions in the channel you want to post the feed
+in.
 
-{{< callout context="danger" title="Danger" icon="outline/alert-octagon" >}}
+{{< /callout >}}
+
+## Adding a YouTube Feed
+
+To add a new feed simply copy the channel URL from YouTube and paste it into the "Link" field under "Add New Feed" (you
+may need to scroll down a bit); then select a channel to post it to. For a visual reference, please see the image below.
+
+<center>
+
+!["Link" field to add a new YouTube feed](./youtube-new-feed.png)
+
+</center>
+
+
+If you are unable to obtain a direct channel URL, similar to<br>
+*https://youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw*, we also support the following URLs:
+
+- Video links (https://youtube.com/watch?v=dQw4w9WgXcQ)
+- Shorts links (https://youtube.com/shorts/pBZ_2pX_8mg)
+- Share links (https://youtu.be/dQw4w9WgXcQ)
+- Live links (https://youtube.com/live/jfKfPfyJRdk)
+- Playlist links (https://youtube.com/playlist?list=PLEamUZtdyTMxwDNQ97Y7im8EwqRyht12R)
+
+Although we make an attempt at extracting the channel from usernames (https://youtube.com/user/MontyPython),
+custom links (https://youtube.com/c/Taskmaster), and handles (https://youtube.com/@TomScottGo), these are not as
+reliable as the links listed above, as we use the first result of a YouTube search to determine the channel via these
+URLs.
+
+If you find yourself having trouble adding a feed using these kinds of URLs, please try to use one of the links listed
+above before asking for help in the [support server](/discord).
+
+{{< callout context="caution" title="Warning: Maximum Number of Feeds" icon="outline/info-circle" >}}
+
+You cannot have more than 10 active YouTube feeds at a time (250 with [Premium](/docs/welcome/premium)). If you have
+that many feeds active, you cannot add more until you disable at least one of those. That disabled excess feed will be
+deleted once you add a new one.
+
+{{< /callout >}}
 
-Do **NOT** fill in both the Channel ID and the Channel URL.
+## Configuring a YouTube Feed
 
-- There may be up to 5-15 minutes of delay for the bot to announce the video after it gets posted.
-- The bot will only announce the video if it's public.
+During setup of a feed there are four more options you can configure, namely:
+
+- mention `@everyone` in the announcement message
+- mention a specific role
+- also publish livestreams
+- also publish shorts
+
+{{< callout context="note" title="Note: Required Bot Permissions" icon="outline/info-circle" >}}
+
+The bot needs mention `@everyone` or "mention this role" permissions if you wish to mention everyone or a specific role
+of your choosing.
 
 {{< /callout >}}
 
-![Showcase of the YouTube feed interface.](./youtube.png)
+You need not configure any of these ahead of time, you can always [edit the feed](#editing-a-youtube-feed) later.
+
+## Editing a YouTube Feed
+
+To edit a feed, scroll down further until you reach the "Current subscribed channels" section. There you will find a
+list of all the feeds you have added.
+
+!["Current subscribed channels" section to edit a YouTube feed](./youtube-edit-feed.png)
+
+Going from left to right of the editable options, you can change the following:
+
+- The Discord channel to post to
+- Mention `@everyone` in the announcement message
+- Mention a specific role
+- Also publish livestreams
+- Also publish shorts
+- Disable the feed until you enable it again
 
-To get notifications from a YouTube channel, simply go to the YouTuber's channel and input either the ID or the Username in their respective field of the followings:
+Once you have made your changes, click the "Save" button on the far right to save your changes. If you instead wish to
+delete the feed, click the "Delete" button just below the "Save" button. None of these options need to be equal across
+all your feeds, you can have different settings for each feed.
 
-- YouTube Channel ID
+You can only save changes to a feed one at a time, so if there are multiple feeds you wish to edit, you have to do so
+separately, saving after each feed you edited.
 
-- YouTube Channel Username
+## Custom Announcement
+
+If you take a look at the top-right of the configuration page, you'll see a field for custom command templates for usage
+in the announcement message provided for YouTube feeds. The default response is the following code:
+
+```yag
+{{.ChannelName}} published a new video! {{.URL}}
+```
+
+You can customize this message to your liking, but bear in mind that using a custom announcement message will override
+the default announcement's mention settings *for all channels*, therefore you will have to implement this logic by
+yourself. Refer to the [mentions functions](https://help.yagpdb.xyz/docs/reference/templates/functions/#mentions) for
+more information.
+
+{{< callout context="danger" title="Danger: Custom Announcement Overrides Settings" icon="outline/alert-octagon" >}}
+
+Using a custom announcement message will override the default announcement's mention settings for all channels. Really.
+
+{{< /callout >}}
 
-If your channel looks like this `youtube.com/user/h3h3Productions` then you would go into the username line and type
-in h3h3Productions.
+### Additional Context Data
 
-If your channel looks like this `youtube.com/channel/UCt-ERbX-2yA6cAqfdKOlUwQ` then you would go into the ID line and
-type in UCt-ERbX-2yA6cAqfdKOlUwQ.
+In addition to the standard context data available to all custom commands, we provide the following additional context
+data:
 
-You can change the channel that the notifications are posted to via the dropdown menu.
+- `{{ .ChannelID }}`: ID of the YouTube Channel.
+- `{{ .ChannelName }}`: Name of the YouTube Channel.
+- `{{ .IsLiveStream }}`: True, if the notification is for a livestream else False.
+- `{{ .IsUpcoming }}`: True, if the notification is for a scheduled release else False.
+- `{{ .VideoID }}`: ID of the video.
+- `{{ .VideoTitle }}`: Title of the video.
+- `{{ .VideoThumbnail }}`: Thumbnail image URL of the video.
+- `{{ .VideoDescription }}`: Description of the video.
+- `{{ .VideoDurationSeconds }}`: Duration of video in seconds.
+- `{{ .Video }}`: Data of the video as available in the [YouTube API][video-yt-api].
+- `{{ .URL }}`: Video URL.
 
-You can also mention everyone by clicking the checkbox under the dropdown menu that says Mention everyone.
+[video-yt-api]: https://pkg.go.dev/google.golang.org/api/youtube/v3#Video