Merge pull request #15 from botlabs-gg/docs/moderation

docs/moderation: document moderation section

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

content/moderation/_index.md

@@ -0,0 +1,7 @@
++++
+archetype = "chapter"
+title = "Moderation"
+weight = 5
++++
+
+{{%children containerstyle="div" style="h2" description="true" %}}

content/moderation/advanced-automoderator/_index.md

@@ -0,0 +1,95 @@
++++
+title = 'Advanced Automoderator'
+weight = 3
++++
+
+A sophisticated automoderator system, allowing for more complex configurations than basic automoderator.
+
+<!--more-->
+
+## Intro
+
+Advanced Automoderator is (quite obviously) a more detailed system than [Basic Automoderator](../basic-automoderator).
+It allows for more flexibility and complex configurations, but the trade-off is that some time investment is required
+to set it up.
+
+Advanced automoderator operates on the basis of user-configurable rules, which trigger on specific actions and
+conditions to produce certain effects. Collections of rules are referred to as rulesets.
+
+Finally, there are lists you can create, which can be used to black- or whitelist words or domains.
+
+## Overview
+
+First, let us explore the available tabs on the main page.
+
+### Global Settings
+
+This tab is your first stop when starting with Advanced Automoderator, as it is where you create new rulesets. Give it a
+telling name and click the **Create** button. This will create a new tab with that name.
+
+Furthermore, this is also the place to create and manage your lists. Lists are used to store words or domains that you
+want to use as black- or whitelist triggers in your rules. More on that under [Lists](#lists).
+
+### Logs
+
+This tab can be useful when troubleshooting or testing your configuration, as it shows who fired what rule in what
+ruleset, at what time, with which trigger. However, it is not a full log of messages, nor does it log moderation
+actions.
+
+## Configuration
+
+With that out of the way, we'll go through how to *actually* make Advanced Automoderator do the thing it's designed to.
+
+### Lists
+
+As mentioned above, lists are used to store words or domains that you want to use as black- or whitelist triggers in your
+rules.
+
+Multiple entries in word lists are separated by either a newline or a space. Entries in word lists must be single words
+containing no spaces; to blacklist complete phrases, use a regex trigger instead.
+
+For website / link lists, specify *just* the site's domain, without any protocol or path. Subdomains will be
+automatically included. Logically, if you want to *only* check against some specific subdomain (and its sub-subdomains),
+you will have to specify just that subdomain.
+
+#### Limitations
+
+You cannot have more than 5 (premium: 25) lists, and each list may not have more than 5000 characters.
+
+### Rulesets
+
+Rulesets are the overarching structure of your automoderator configuration. They are the containers for your rules, and
+can be toggled on or off on the control panel, or with the `automod toggle <ruleset name>` command.
+
+Several configuration options are available for each ruleset:
+
+- **Name** — The name of the ruleset.
+- **Enable ruleset** — Whether the ruleset is active or not.
+- **Ruleset scoped conditions** — Conditions that apply to all rules in the ruleset.
+- **Create a new rule** — Add a new rule to the ruleset.
+
+#### Limitations
+
+You cannot have more than 10 (premium: 25) rulesets. If you run into that limit, consider merging some rulesets
+together, or removing some that are no longer needed.
+
+### Rules
+
+Rules are the actual meat of your automoderator configuration. They consist of triggers, conditions, and effects. We
+will call those three things collectively [*rule parts*](#rule-parts).
+
+A rule can have multiple triggers, conditions, and effects. All of them are optional, but a rule without at least one
+trigger and effect is pointless.
+
+When checking whether a rule applies, triggers follow the OR logic, while conditions and effects follow the AND logic.
+That means for a rule to apply, *only one* trigger has to be true, whilst *all* conditions need be met, which
+then fires *all* effects.
+
+#### Limitations
+
+Across all rulesets, you cannot have more than 25 (premium: 150) rules. A rule may not consist of more than 25 rule
+parts.
+
+### Rule Parts
+
+{{%children containerstyle="div" style="h4" description="true" %}}

content/moderation/advanced-automoderator/conditions.md

@@ -0,0 +1,124 @@
++++
+title = 'Conditions'
+weight = 2
++++
+
+Conditions impose more fine-grained control on Advanced Automoderator rules. This page will cover the different types
+of conditions and how to use them.
+
+<!--more-->
+
+## Quick Intro
+
+This page lists all the available conditions in the order as they appear on the control panel. Use the Table of Contents
+in the top left corner of this page alongside your browser's search function to quickly navigate to the condition you're
+looking for.
+
+By extension, these conditions are also available as ruleset scoped conditions.
+
+### Condition Logic
+
+All conditions have to be met in order for a rule to execute — that is, the conditions are combined according to the
+logical AND operator.
+
+{{% notice style="warning" %}}
+
+Ensure that the conditions you set are not in conflict or mutually exclusive, as this will cause your rule to never
+trigger.
+
+A common example of this is setting both *[Edited message](#edited-message)* and *[New message](#new-message)*
+conditions in the same rule. Since a message can't be both new and edited at the same time, the rule will never trigger.
+
+{{% /notice %}}
+
+
+#### Ignored Roles
+
+Have the rule ignore users with selected roles. This is useful for excluding moderators or bots from the rule.
+
+- **Roles**<br>
+    The roles to ignore. Select as many as you like. (Default: None)
+
+#### Require Roles
+
+Like [Ignored Roles](#ignored-roles), with following optional setting:
+
+- **Require all selected roles**<br>
+    Whether the user must have all selected roles, or just any. (Default: off)
+
+#### Ignore Channels
+
+Have the rule ignore messages from selected channels, for example, to exclude a bot channel.
+
+- **Channels**<br>
+    The channels to ignore. Select as many as you like. (Default: None)
+
+#### Active in channels
+
+Just like [Ignore Channels](#ignore-channels), but only apply the rule to messages from selected channels.
+
+#### Account age above
+
+Only apply this rule if the user's account is older than the specified duration in minutes.
+
+- **Age in minutes**<br>
+    The minimum account age in minutes. (Default: 0)
+
+#### Account age below
+
+Only apply this rule if the user's account is younger than the specified duration in minutes.
+
+- **Age in minutes**<br>
+    The maximum account age in minutes. (Default: 0)
+
+#### Server Member duration above
+
+Only apply this rule if the user has been a member of the server for longer than the specified duration in minutes.
+
+This condition directly conflicts with the *[New Member](./triggers#new-member)* trigger.
+
+- **Age in minutes**<br>
+    The minimum member duration in minutes. (Default: 0)
+
+#### Server Member duration below
+
+Like [Server Member duration above](#server-member-duration-above), but only apply this rule if the user has been a
+member of the server for less than the specified duration in minutes.
+
+#### Ignore Bots
+
+Have the rule ignore messages from bots. This conflicts with the *[Only Bots](#only-bots)* condition.
+
+#### Only Bots
+
+Only apply this rule to messages from bots. This conflicts with the *[Ignore Bots](#ignore-bots)* condition.
+
+#### Ignore Categories
+
+Have the rule ignore messages from channels in selected categories.
+
+- **Categories**<br>
+    The categories to ignore. Select as many as you like. (Default: None)
+
+#### Active in Categories
+
+Only apply this rule if it was triggered in one of the selected categories.
+
+- **Categories**<br>
+    The categories to apply this rule to. Select as many as you like. (Default: None)
+
+#### New message
+
+Only apply this rule to a newly sent message. This condition is mutually exclusive with *[Edited message](#edited-message)*.
+
+#### Edited message
+
+Only apply this rule to an edited message. This condition is mutually exclusive with *[New message](#new-message)*.
+
+#### Active in threads
+
+Only apply this rule to messages in threads.
+
+#### Ignore threads
+
+Do not apply this rule to messages in threads.

content/moderation/advanced-automoderator/effects.md

@@ -0,0 +1,138 @@
++++
+title = 'Effects'
+weight = 3
++++
+
+Effects define what happens when a rule is triggered and all conditions are met. This page will cover the different
+kinds of effects available to you in Advanced Automoderator.
+
+<!--more-->
+
+## Quick Intro
+
+This page lists all the available effects in the order as they appear on the control panel. Use the Table of Contents
+in the top left corner of this page alongside your browser's search function to quickly navigate to the effect you're
+looking for.
+
+### Effect Logic
+
+All effects will be executed once all prior checks are met — that is, the effects are combined according to the logical
+AND operator.
+
+#### Delete Message
+
+Delete the message that triggered the rule.
+
+#### +Violation
+
+Add a violation to the user's record. This is useful for tracking user behavior over time.
+
+- **Name**<br>
+    The name of the violation. (Default: None)
+
+#### Kick user
+
+Kick the user that triggered the rule.
+
+- **Custom message**<br>
+    A custom reason for the kick. (Default: None)
+
+#### Ban user
+
+Ban the user that triggered the rule.
+
+- **Duration**<br>
+    The duration of the ban in minutes. 0 for permanent. (Default: 0)
+- **Custom message**<br>
+    A custom reason for the ban. (Default: None)
+- **Number of days to delete**<br>
+    How many days of that user's message history to delete. 0 to 7 days. (Default: 0)
+
+#### Mute user
+
+Mute the user that triggered the rule.
+
+- **Duration**<br>
+    The duration of the mute in minutes. 0 for permanent. (Default: 0)
+- **Custom message**<br>
+    A custom reason for the mute. (Default: None)
+
+#### Warn user
+
+Warn the user that triggered the rule.
+
+- **Custom message**<br>
+    A custom reason for the warning. (Default: None)
+
+#### Set nickname
+
+Set the nickname of the user that triggered the rule.
+
+- **New Nickname**<br>
+    The new nickname for the user. Empty for removal. (Default: None)
+
+#### Reset violations
+
+Reset the violations of the user that triggered the rule.
+
+- **Name**<br>
+    The name of the violation to reset. (Default: None)
+
+#### Delete multiple messages
+
+Delete multiple messages from the user that triggered the rule.
+
+- **Number of messages**<br>
+    The number of messages to delete. (Default: 3)
+- **Max age**<br>
+    The maximum age of the messages to delete in seconds. (Default: 15)
+
+#### Give role
+
+Give a role to the user that triggered the rule.
+
+- **Duration**<br>
+    The duration of the role in seconds. 0 for permanent. (Default: 0)
+- **Role**<br>
+    The role to give to the user. (Default: first role in hierarchy)
+
+#### Enable Channel slowmode
+
+Enable slowmode in the channel where the rule was triggered.
+
+- **Duration**<br>
+    The duration of the slowmode in seconds. 0 for permanent. (Default: 0)
+- **Ratelimit**<br>
+    The minimum time that has to pass between a single user's messages. (Default: 0)
+
+#### Remove role
+
+Remove a role from the user that triggered the rule.
+
+- **Duration**<br>
+    The duration of the role in seconds. 0 for permanent. (Default: 0)
+- **Role**<br>
+    The role to remove from the user. (Default: first role in hierarchy)
+
+#### Send Message
+
+Send a custom message.
+
+- **Custom message**<br>
+    The message to send. Max 280 characters. (Default: (empty))
+- **Delete after**<br>
+    The duration in seconds after which to delete the message. 0 for never. Max 3600 seconds. (Default: 0)
+- **Ping user**<br>
+    Whether to ping the user that triggered the rule. (Default: false)
+- **Channel to send to**<br>
+    The channel to send the message to. (Default: same channel)
+
+#### Timeout user
+
+Timeout the user that triggered the rule. This is different from [Mute user](#mute-user) as it uses Discord's timeout
+functionality instead of applying a muted role.
+
+- **Duration**<br>
+    The duration of the timeout in minutes. (Default: 0)
+- **Custom message**<br>
+    A custom reason for the timeout. (Default: None)