clean this up when home

1 files changed, 342 insertions, 0 deletions

diff --git a/docs/configuration.md b/docs/configuration.md
new file mode 100644
index 0000000..cb4f2bb
--- /dev/null
+++ b/docs/configuration.md
@@ -0,0 +1,342 @@
+# 📝 Configuration
+Haven't set up the bot yet? Check out [Setting up the bot](setup.md) first!
+
+## Table of contents
+- [Configuration file](#configuration-file) (start here)
+- [Adding new options](#adding-new-options)
+- [Required options](#required-options)
+- [Other options](#other-options)
+- [config.ini vs config.json](#configini-vs-configjson)
+- [Other formats](#other-formats)
+- [Environment variables](#environment-variables)
+
+## Configuration file
+All bot options are saved in a configuration file in the bot's folder.
+This is created during the [setup](setup.md) and is generally either `config.ini` or, if you've been using the bot for
+longer, `config.json`.
+
+The instructions on this page are for `config.ini` but can be adapted to `config.json` as well.
+See [config.ini vs config.json](#configini-vs-configjson) for more details.
+Note that the format of `.ini` and `.json` are different -- you can't simply rename a `.json` to `.ini` or
+vice versa.
+
+## Adding new options
+To add a new option to your `config.ini`, open the file in a text editor such as notepad.
+Each option is put on a new line, and follows the format `option = value`. For example, `mainGuildId = 1234`.
+
+**You need to restart the bot for configuration changes to take effect!**
+
+You can add comments in the config file by prefixing the line with `#`. Example:
+```ini
+# This is a comment
+option = value
+```
+
+### Toggle options
+Some options like `allowMove` are "**Toggle options**": they control whether certain features are enabled (on) or not (off).
+* To enable a toggle option, set its value to `on`, `true`, or `1`
+* To disable a toggle option, set its value to `off`, `false`, or `0`
+* E.g. `allowMove = on` or `allowMove = off`
+
+### "Accepts multiple values"
+Some options are marked as "**Accepts multiple values**". To give these options multiple values,
+write the option as `option[] = value` and repeat for every value. For example:
+
+```ini
+inboxServerPermission[] = kickMembers
+inboxServerPermission[] = manageMessages
+```
+
+You can also give these options a single value in the usual way, i.e. `inboxServerPermission = kickMembers`
+
+### Multiple lines of text
+For some options, such as `greetingMessage`, you might want to add text that spans multiple lines.
+To do that, use the same format as with "Accepts multiple values" above:
+
+```ini
+greetingMessage[] = Welcome to the server!
+greetingMessage[] = This is the second line of the greeting.
+greetingMessage[] = 
+greetingMessage[] = Fourth line! With an empty line in the middle.
+```
+
+## Required options
+
+#### token
+The bot user's token from [Discord Developer Portal](https://discordapp.com/developers/).
+
+#### mainGuildId
+Your server's ID, wrapped in quotes.
+
+#### mailGuildId
+For a two-server setup, the inbox server's ID.  
+For a single-server setup, same as [mainGuildId](#mainguildid).
+
+#### logChannelId
+ID of a channel on the inbox server where logs are posted after a modmail thread is closed
+
+## Other options
+
+#### accountAgeDeniedMessage
+**Default:** `Your Discord account is not old enough to contact modmail.`  
+See `requiredAccountAge` below
+
+#### allowMove
+**Default:** `off`  
+If enabled, allows you to move threads between categories using `!move <category>`
+
+#### allowUserClose
+**Default:** `off`  
+If enabled, users can use the close command to close threads by themselves from their DMs with the bot
+
+#### alwaysReply
+**Default:** `off`  
+If enabled, all messages in modmail threads will be sent to the user without having to use `!r`.  
+To send internal messages in the thread when this option is enabled, prefix them with `!note` (using your `prefix`),
+e.g. `!note This is an internal message`.
+
+#### alwaysReplyAnon
+**Default:** `off`  
+If `alwaysReply` is enabled, this option controls whether the auto-reply is anonymous
+
+#### attachmentStorage
+**Default:** `local`  
+Controls how attachments in modmail threads are stored. Possible values:
+* **local** - Files are saved locally on the machine running the bot
+* **discord** - Files are saved as attachments on a special channel on the inbox server. Requires `attachmentStorageChannelId` to be set.
+
+#### attachmentStorageChannelId
+**Default:** *None*  
+When using attachmentStorage is set to "discord", the id of the channel on the inbox server where attachments are saved
+
+#### botMentionResponse
+**Default:** *None*  
+If set, the bot auto-replies to bot mentions (pings) with this message. Use `{userMention}` in the text to ping the user back.
+
+#### categoryAutomation.newThread
+**Default:** *None*  
+ID of the category where new threads are opened. Also functions as a fallback for `categoryAutomation.newThreadFromGuild`.
+
+#### categoryAutomation.newThreadFromGuild.GUILDID
+**Default:** *None*  
+When running the bot on multiple main servers, this allows you to specify new thread categories for users from each guild. Example:
+```ini
+# When the user is from the server ID 94882524378968064, their modmail thread will be placed in the category ID 360863035130249235
+categoryAutomation.newThreadFromGuild.94882524378968064 = 360863035130249235
+# When the user is from the server ID 541484311354933258, their modmail thread will be placed in the category ID 542780020972716042
+categoryAutomation.newThreadFromGuild.541484311354933258 = 542780020972716042
+```
+
+#### closeMessage
+**Default:** *None*  
+If set, the bot sends this message to the user when the modmail thread is closed.
+
+#### commandAliases
+**Default:** *None*  
+Custom aliases/shortcuts for commands. Example:
+```ini
+# !mv is an alias/shortcut for !move
+commandAliases.mv = move
+# !x is an alias/shortcut for !close
+commandAliases.x = close
+```
+
+#### enableGreeting
+**Default:** `off`  
+When enabled, the bot will send a greeting DM to users that join the main server.
+
+#### greetingAttachment
+**Default:** *None*  
+Path to an image or other attachment to send as a greeting. Requires `enableGreeting` to be enabled.
+
+#### greetingMessage
+**Default:** *None*  
+Message to send as a greeting. Requires `enableGreeting` to be enabled. Example:
+```ini
+greetingMessage[] = Welcome to the server!
+greetingMessage[] = Remember to read the rules.
+```
+
+#### guildGreetings
+**Default:** *None*  
+When running the bot on multiple main servers, this allows you to set different greetings for each server. Example:
+```ini
+guildGreetings.94882524378968064.message = Welcome to server ID 94882524378968064!
+guildGreetings.94882524378968064.attachment = greeting.png
+
+guildGreetings.541484311354933258.message[] = Welcome to server ID 541484311354933258!
+guildGreetings.541484311354933258.message[] = Second line of the greeting.
+```
+
+#### ignoreAccidentalThreads
+**Default:** `off`  
+If enabled, the bot attempts to ignore common "accidental" messages that would start a new thread, such as "ok", "thanks", etc.
+
+#### inboxServerPermission
+**Default:** *None*  
+**Accepts multiple values.** Permission name, user id, or role id required to use bot commands on the inbox server.
+See ["Permissions" on this page](https://abal.moe/Eris/docs/reference) for supported permission names (e.g. `kickMembers`).
+
+#### timeOnServerDeniedMessage
+**Default:** `You haven't been a member of the server for long enough to contact modmail.`  
+If `requiredTimeOnServer` is set, users that are too new will be sent this message if they try to message modmail.
+
+#### mentionRole
+**Default:** `here`  
+**Accepts multiple values.** Role that is mentioned when new threads are created or the bot is mentioned.
+Accepted values are "here", "everyone", or a role id.
+Requires `pingOnBotMention` to be enabled.
+Set to an empty value (`mentionRole=`) to disable these pings entirely.
+
+#### mentionUserInThreadHeader
+**Default:** `off`  
+If enabled, mentions the user messaging modmail in the modmail thread's header.
+
+#### newThreadCategoryId
+**Default:** *None*  
+**Deprecated.** Same as `categoryAutomation.newThread`.
+
+#### pingOnBotMention
+**Default:** `on`  
+If enabled, the bot will mention staff (see `mentionRole` option) on the inbox server when the bot is mentioned on the main server.
+
+#### plugins
+**Default:** *None*  
+**Accepts multiple values.** External plugins to load on startup. See [Plugins](plugins.md) for more information.
+
+#### port
+**Default:** `8890`  
+Port to use for attachments (when `attachmentStorage` is set to `local`) and logs.  
+Make sure to do the necessary [port forwarding](https://portforward.com/) and add any needed firewall exceptions so the port is accessible from the internet.
+
+#### prefix
+**Default:** `!`  
+Prefix for bot commands
+
+#### relaySmallAttachmentsAsAttachments
+**Default:** `off`  
+If enabled, small attachments from users are sent as real attachments rather than links in modmail threads.
+The limit for "small" is 2MB by default; you can change this with the `smallAttachmentLimit` option.
+
+#### requiredAccountAge
+**Default:** *None*  
+Required account age for contacting modmail (in hours). If the account is not old enough, a new thread will not be created and the bot will reply with `accountAgeDeniedMessage` (if set) instead.
+
+#### requiredTimeOnServer
+**Default:** *None*  
+Required amount of time (in minutes) the user must be a member of the server before being able to contact modmail. If the user hasn't been a member of the server for the specified time, a new thread will not be created and the bot will reply with `timeOnServerDeniedMessage` (if set) instead.
+
+#### responseMessage
+**Default:** `Thank you for your message! Our mod team will reply to you here as soon as possible.`  
+The bot's response to the user when they message the bot and open a new modmail thread
+
+#### rolesInThreadHeader
+**Default:** `off`  
+If enabled, the user's roles will be shown in the modmail thread header
+
+#### smallAttachmentLimit
+**Default:** `2097152`  
+Size limit of `relaySmallAttachmentsAsAttachments` in bytes (default is 2MB)
+
+#### snippetPrefix
+**Default:** `!!`  
+Prefix for snippets
+
+#### snippetPrefixAnon
+**Default:** `!!!`  
+Prefix to use snippets anonymously
+
+#### status
+**Default:** `Message me for help`  
+The bot's "Playing" text
+
+#### syncPermissionsOnMove
+**Default:** `on`  
+If enabled, channel permissions for the thread are synchronized with the category when using `!move`. Requires `allowMove` to be enabled.
+
+#### threadTimestamps
+**Default:** `off`  
+If enabled, modmail threads will show accurate UTC timestamps for each message, in addition to Discord's own timestamps.
+Logs show these always, regardless of this setting.
+
+#### typingProxy
+**Default:** `off`  
+If enabled, any time a user is typing to modmail in their DMs, the modmail thread will show the bot as "typing"
+
+#### typingProxyReverse
+**Default:** `off`  
+If enabled, any time a moderator is typing in a modmail thread, the user will see the bot "typing" in their DMs
+
+#### updateNotifications
+**Default:** `on`  
+If enabled, the bot will automatically check for new bot updates periodically and notify about them at the top of new modmail threads
+
+#### url
+**Default:** *None*  
+URL to use for attachment and log links. Defaults to `http://IP:PORT`.
+
+#### useNicknames
+**Default:** `off`  
+If enabled, mod replies will use their nicknames (on the inbox server) instead of their usernames
+
+## config.ini vs config.json
+Earlier versions of the bot instructed you to create a `config.json` instead of a `config.ini`.
+**This is still fully supported, and will be in the future as well.**
+However, there are some differences between `config.ini` and `config.json`.
+
+### Formatting
+*See [the example on the Wikipedia page for JSON](https://en.wikipedia.org/wiki/JSON#Example)
+for a general overview of the JSON format.*
+
+* In `config.json`, all text values and IDs need to be wrapped in quotes, e.g. `"mainGuildId": "94882524378968064"`
+* In `config.json`, all numbers (other than IDs) are written without quotes, e.g. `"port": 3000`
+
+### Toggle options
+In `config.json`, valid values for toggle options are `true` and `false` (not quoted),
+which correspond to `on` and `off` in `config.ini`.
+
+### "Accepts multiple values"
+Multiple values are specified in `config.json` using arrays:
+```json
+{
+  "inboxPermission": [
+    "kickMembers",
+    "manageMessages"
+  ]
+}
+```
+
+### Multiple lines of text
+Since `config.json` is parsed using [JSON5](https://json5.org/), multiple lines of text are supported
+by escaping the newline with a backslash (`\ `):
+```json5
+{
+  "greetingMessage": "Welcome to the server!\
+This is the second line of the greeting."
+}
+```
+
+## Other formats
+Loading config values programmatically is also supported.
+Create a `config.js` in the bot's folder and export the config object with `module.exports`.
+All other configuration files take precedence, so make sure you don't have both.
+
+## Environment variables
+Config options can be passed via environment variables.
+
+To get the name of the corresponding environment variable for an option, convert the option to SNAKE_CASE with periods
+being replaced by two underscores and add `MM_` as a prefix. If adding multiple values for the same option, separate the
+values with two pipe characters: `||`.
+
+Examples:
+* `mainGuildId` -> `MM_MAIN_GUILD_ID`
+* `commandAliases.mv` -> `MM_COMMAND_ALIASES__MV`
+* From:  
+  ```ini
+  inboxServerPermission[] = kickMembers
+  inboxServerPermission[] = manageMessages
+  ```  
+  To:  
+  `MM_INBOX_SERVER_PERMISSION=kickMembers||manageMessages`
+
+The `port` option also accepts the environment variable `PORT` without a prefix, but `MM_PORT` takes precedence.