[docs] Add raffle documentation

Signed-off-by: Knut Ahlers <knut@ahlers.me>

docs/content/modules/_index.md

@@ -0,0 +1,10 @@
+---
+title: Modules
+---
+
+{{< lead >}}
+Aside of the core functionality of being a bot in a Twitch channel the bot contains additional modules to make channel management easier.
+{{< /lead >}}
+
+- The bot can serve all of your [**Overlays**]({{< ref "../overlays/_index.md" >}}) for you providing you with sound-alerts, alerts for various events and everything you can imagine yourself using Custom Events
+- With the [**Raffle**]({{< ref "raffle.md" >}}) module you can create giveaways with various settings

docs/content/modules/raffle.md

@@ -0,0 +1,66 @@
+---
+title: Raffle
+---
+
+{{< lead >}}
+Using the raffle module you can create giveaways with various settings, timers and pick one or multiple winners. You just have to send the good yourself…
+{{< /lead >}}
+
+## General Overview
+
+![]({{< static "raffle-overview.png" >}})
+
+In the overview you can see a list of your raffles and their status. You can edit, start / stop, copy, delete them or access the list of entrants from here.
+
+The screenshot above shows one draft of a raffle together with one currently active.
+
+![]({{< static "raffle-entrants.png" >}})
+
+You can access the entrants list through the "group of people" button in the raffle overview. This becomes available as soon as the raffle has started.
+
+In this list you can see the status, the nickname and the time of entry for each entrant. The status will be a person (<i class="fas fa-user"></i>) for someone joined through the **Everyone** allowance, a heart (<i class="fas fa-heart"></i>) for a follower, a star (<i class="fas fa-star"></i>) for a subscriber and a diamond (<i class="fas fa-gem"></i>) for a VIP. The list will update itself when there are changes in the entree-list.
+
+![]({{< static "raffle-entrants-closed.png" >}})
+
+After the raffle has been closed (either through the timer or by clicking the button) a winner can be picked through the "Pick Winner" button. A winner will display a crown before their status, the first chat message after being picked below the name and a "recycle" button to re-draw them. If you choose to re-draw a winner the crown will get striked and greyed out. A re-drawn winner can not be picked again (re-rdrawing without any candidates will cause an error and void the slot)!
+
+### Recommendations
+
+- As you can see below there are many options to configure and you probably will use the same texts (and maybe even some other options too) in every raffle. That's why you can see a `TEMPLATE` raffle in the screenshot above. That's a fully configured and never started raffle I keep around. When starting a new raffle I will just use the "copy" button to create a copy of that raffle, edit the copy, adjust the title and maybe options I don't like and can start the raffle saving a lot of work in the process especially creating the texts. You can have as many templates as you like if you're doing different raffles over and over.
+
+## Raffle Configuration
+
+### General Settings
+
+![]({{< static "raffle-general-config.png" >}})
+
+Within the general settings you will configure how your raffle behaves once started:
+
+- **Channel** configures where it will take place: Straight forward, put your channel without the leading `#`.
+- **Keyword** is what users must type in order to participate. In general they are used to type commands like `!enter` or `!key` for Steam-Key giveaways so I'd advice to stick to a command format. You should ensure not to use the same command in two raffles active at the same time though it is possible: if two raffles are using the same keyword, the user writing the keyword once will enter **both** raffles.
+- **Title** should reflect what you're giving away and is available in the texts (more below). So for example this could be `Steam-Key: Starfield`.
+- **Allowed Entries** configure who can take part in your giveaway. Pay attention these conditions are **or**-connected, so the chatter must only have one condition matching and not all of them!
+  - **Everyone** is straight forward: No conditions are imposed.
+  - **Followers, since `X` min** means all followers can participate if they are followed at least `X` minutes ago.
+  - **Subscribers** is straight forward again: If they have a subscriber-badge, they can join.
+  - **VIPs** is the same just they do need a VIP badge.
+- **Luck Modifiers** are kinda tricky as they configure the size of each ticket and therefore manipulate the probability to be chosen. As stated in the text below the base modifier for **Everyone** is `1.0` and you can modifiy the "luck" for all others. Pay attention with this: if you for example disable the VIPs checkbox in **Allowed Entries** the VIPs luck modifier will **not** be used! That VIP will then enter as a subscriber or follower or even as "everyone" and get the respective modifier.
+- **Times** configure when and for how long the raffle will take place:
+  - **Auto-Start** can be configured and if it is, the raffle will open itself at that point of time (within 1 minute). If you don't set this you need to start the raffle yourself.
+  - **Duration** configures how long the raffle will run. This is only relevant if **Close At** is unset. (Internally on starting the raffle **Close At** will be set to `now + duration` if **Close At** is empty.)
+  - **Close At** marks the end of the raffle. The raffle will automatically get closed at that point of time (within 1 minute).
+  - **Respond in** adds a time window where the bot will record the first message of the picked user after they have been picked. You will see that message in the entrants list: Useful for channels with a lot going on in the chat so you don't miss their response. After this time window is over no response will be recorded.
+
+### Texts
+
+![]({{< static "raffle-texts.png" >}})
+
+The texts do support templating and do have the same format like other templates i.e. in rules. You can enable or disable each of them though I'd recommend to keep all of them enabled (maybe except the "failed entry" message).
+
+- **Message on successful entry** will be posted as soon as the chatter is added to the entrants list.
+- **Message on failed entry** will be posted in case the chatter is not entered (could be they are already entered or the bot encountered any other error while adding them).
+- **Message on winner draw** will be posted for the chatter getting picked when drawing the winner: if you disable this you still can tell them they won when picking them.
+- **Periodic reminder every `X` min** is a message to remember chatters (and tell new ones) there is a raffle open. It will be posted every `X` minutes, first time when opening the raffle.
+- **Message on raffle close** will be posted when the raffle closes (either you closed it manually or the **Close At** time is reached).
+
+Within the templates you do have access to the variables `.user` and `.raffle` (which represents the raffle object). Have a look at the default templates for examples what you can do with them.

docs/layouts/shortcodes/static.html

@@ -0,0 +1,5 @@
+{{- .Scratch.Set "path" (.Get 0) -}}
+{{- if hasPrefix (.Scratch.Get "path") "/" -}}
+  {{- .Scratch.Set "path" (slicestr (.Scratch.Get "path") 1) -}}
+{{- end -}}
+{{- .Scratch.Get "path" | absLangURL -}}

docs/static/raffle-entrants-closed.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a188c2de21f24c3db3ba56d123e1f76fb6920456d5e6f388af7eeecf3e1d85df
+size 14721

docs/static/raffle-entrants.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4ef7d42174f56cdb00e028b3f23b4ab9e027fd9572d44bd066b4692e7940c1e0
+size 12866

docs/static/raffle-general-config.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7ed4fbfafd57ae86821ca2ed8ea6a383e0b4453dc3ee7942010e23f886f5846c
+size 78876

docs/static/raffle-overview.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5f47ddf30ae4211d7a0a323182b1331521a09915f73f5a0bcc5b7c6f01ca7310
+size 16172

docs/static/raffle-texts.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c484cda001007c2817c4e0f989c2614bc11213f361b07c9b7ad57fb15c27c07d
+size 68284