Setup mkdocs

README.md

@@ -1,4 +1,4 @@
-# <img src="https://github.com/esmBot/esmBot/raw/master/esmbot.png" width="128"> esmBot
+# <img src="https://github.com/esmBot/esmBot/raw/master/docs/assets/esmbot.png" width="128"> esmBot
 [![esmBot Support](https://discordapp.com/api/guilds/592399417676529688/embed.png)](https://discord.gg/vfFM7YT) ![GitHub license](https://img.shields.io/github/license/esmBot/esmBot.svg)
 
 

docs/config.md

@@ -2,13 +2,15 @@
 esmBot uses environment variables for configuration. To make managing them easier, a `.env` file is included with the bot and can be used to load the variables on bot startup.
 
 Here's an overview of the environment variables required to run the bot:
+
 - `NODE_ENV`: Used for tuning the bot to different environments. If you don't know what to set it to, leave it as is.
-- `TOKEN`: Your bot's token. You can find this at https://discord.com/developers/applications under your application's Bot tab.
+- `TOKEN`: Your bot's token. You can find this [here](https://discord.com/developers/applications) under your application's Bot tab.
 - `DB`: The database connection string. By default the `sqlite` and `postgresql` protocols are available, but this can be expanded by putting proper DB driver scripts into `utils/database/`. You can also set this to `dummy` to make the bot not use a database at all.
 - `OWNER`: Your Discord user ID. This is used for granting yourself access to certain management commands. Adding multiple users is supported by separating the IDs with a comma; however, this is not recommended for security purposes.
 - `PREFIX`: The bot's default command prefix. Note that servers can set their own individual prefixes via the `prefix` command.
 
 Here's an overview of the variables that are not necessarily required for the bot to run, but can greatly enhance its functionality:
+
 - `STAYVC`: Set this to true if you want the bot to stay in voice chat after playing music/a sound effect. You can make it leave by using the stop command.
 - `DBL`: An API token from [Top.gg](https://top.gg/). Unnecessary for most users since Top.gg tends to ban forks of bots like esmBot from their list.
 - `TENOR`: An API token from [Tenor](https://tenor.com/gifapi). This is required for using GIFs from Tenor.

docs/custom-commands.md

@@ -4,7 +4,7 @@ esmBot has a flexible command handler, allowing you to create new commands and c
 ## Directory Structure
 The bot loads commands from subdirectories inside of the `commands` directory, which looks something like this by default:
 ```
-commands
+commands/
   - fun
     > cat.js
     > ...
@@ -40,6 +40,7 @@ As you can see, the first thing we do is import the Command class. We then creat
 The default command name is the same as the filename that you save it as, excluding the `.js` file extension. If you ever want to change the name of the command, just rename the file.
 
 The parameters available to your command consist of the following:
+
 - `this.client`: An instance of an Eris [`Client`](https://abal.moe/Eris/docs/Client), useful for getting info or performing lower-level communication with the Discord API.
 - `this.cluster`: The ID of the eris-fleet cluster that the command is being run from. This should be a number greater than or equal to 0.
 - `this.worker`: The ID of the current eris-fleet worker. This should be a number greater than or equal to 0.
@@ -52,16 +53,19 @@ The parameters available to your command consist of the following:
 - `this.options`: When run as a "classic" command, this is an object of special arguments (e.g. `--argument=true`) passed to the command. These arguments are stored in a key/value format, so following the previous example, `this.options.argument` would return true. When run as a slash command, this is an object of every argument passed to the command.
 
 Some options are only available depending on the context/original message type, which can be checked with `this.type`. The options only available with "classic" messages are listed below:
+
 - `this.message`: An Eris [`Message`](https://abal.moe/Eris/docs/Message) object of the message that the command was run from, useful for interaction.
 - `this.args`: An array of text arguments passed to the command.
 - `this.content`: A string of the raw content of the command message, excluding the prefix and command name.
 - `this.reference`: An object that's useful if you ever decide to reply to a user inside the command. You can use [`Object.assign`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign) to combine your message content with this parameter.
 
 The options only available with "application"/slash commands are listed below:
+
 - `this.interaction`: An Eris [`CommandInteraction`](https://abal.moe/Eris/docs/CommandInteraction) object of the incoming slash command data. 
 - `this.optionsArray`: A raw array of command options. Should rarely be used.
 
 Some static fields are also available and can be set depending on your command. These fields are listed below:
+
 - `description`: Your command's description, which is shown in the help command.
 - `aliases`: An array of command aliases. People will be able to run the command using these as well as the normal command name.
 - `arguments`: An array of command argument types, which are shown in the help command.

docs/index.md

@@ -0,0 +1,3 @@
+Welcome to the esmBot documentation site!
+
+You're probably looking for the [Setup](setup.md) page. If you're an end user looking to invite the bot, head over to [https://projectlounge.pw/invite](https://projectlounge.pw/invite).

docs/postgresql.md

@@ -1,37 +1,34 @@
 # PostgreSQL
 Here are some instructions for setting up PostgreSQL for use with esmBot.
 
-**1. Install PostgreSQL.**
+### 1. Install PostgreSQL.
 
-#### Debian/Ubuntu
+=== "Debian/Ubuntu"
     ```sh
     sudo apt-get install postgresql postgresql-client
     ```
-
+=== "Fedora/RHEL"
-#### Fedora
     ```sh
     sudo dnf install postgresql postgresql-server
     ```
-
+=== "Alpine"
-#### Alpine
     ```sh
     doas apk add postgresql
     ```
-
+=== "Arch/Manjaro"
-#### Arch/Manjaro
     ```sh
     sudo pacman -S postgresql
     ```
 
 ***
 
-**2. (Optional) Tune PostgreSQL.**
+### 2. (Optional) Tune PostgreSQL.
 
 [PGTune](https://pgtune.leopard.in.ua/) is a useful tool for generating configuration files for your PostgreSQL database. It is highly recommended that you generate a config using this tool as it can increase stability and performance.
 
 ***
 
-**3. Create the bot user and database.**
+### 3. Create the bot user and database.
 
 When you install PostgreSQL, it'll create a new user on your system that acts as the "superuser" of the database. You'll need to run Postgres commands as this user; however, you can run a command as that user without switching to it by using `sudo`.
 
@@ -58,6 +55,8 @@ POSTGRES_USER=esmbot POSTGRES_DB=esmbot utils/psqlinit.sh
 ```
 You're done!
 
+***
+
 ### Troubleshooting
 If you get an error like `error: permission denied for table counts` when attempting to run the bot, try running these commands in the PostgreSQL shell:
 ```sql

docs/setup.md

@@ -1,50 +1,52 @@
 # Setup
 Here are some instructions to get esmBot up and running from source.
 
-Recommended system requirements:
+??? check "Recommended system requirements"
     - 64-bit CPU/operating system
     - Quad-core CPU or better
     - 1GB or more of RAM
-- Linux-based operating system or virtual machine (Ubuntu 22.04 LTS is recommended)
+    - Linux-based operating system or virtual machine ([Ubuntu 22.04 LTS](https://ubuntu.com/download/server) or [Fedora 36](https://getfedora.org/) are recommended)
 
+!!! warning
     If you want to run the bot on Windows, [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10) is recommended. This guide is somewhat Linux-centric, so for now you're mostly on your own if you decide not to use WSL.
 
 If you have any further questions regarding setup, feel free to ask in the #self-hosting-support channel on the [esmBot Support server](https://projectlounge.pw/support).
 
-## Setup
+### 1. Install the required native dependencies.
-#### 1. Install the required native dependencies.
+Choose the distro you're using below for insallation instructions.
-**Debian (bookworm)/Ubuntu (22.04 or later)**  
+=== "Debian/Ubuntu"
+    These instructions apply to Debian version 12 (bookworm) or Ubuntu version 22.04 (jammy) or later.
     ```sh
     sudo apt-get install git curl build-essential cmake ffmpeg sqlite3 ttf-mscorefonts-installer libmagick++-dev libvips-dev libcgif-dev libgirepository1.0-dev fonts-noto-color-emoji libimagequant-dev meson
     ```
     On older Debian/Ubuntu versions, you may need to install some of these packages (notably libcgif-dev and meson) through alternative methods.
+=== "Fedora/RHEL"
+    These instructions apply to Fedora 36/RHEL 9 or later.
 
-**Fedora/RHEL**
+    Some of these packages require that you add the RPM Fusion and/or EPEL repositories. You can find instructions on how to add them [here](https://rpmfusion.org/Configuration).
-Some of these packages require that you add the RPM Fusion repository. You can find instructions on how to add it here: https://rpmfusion.org/Configuration 
-RHEL users may also need to add the EPEL repository. Instructions for adding it can be found here: https://docs.fedoraproject.org/en-US/epel/
     ```sh
     sudo dnf install git curl cmake ffmpeg sqlite gcc-c++ libcgif-devel ImageMagick-c++-devel vips-devel libimagequant-devel gobject-introspection-devel google-noto-emoji-color-fonts meson
     ```
     On RHEL-based distros like AlmaLinux and Rocky Linux, you may need to add [Remi's RPM Repository](https://rpms.remirepo.net) for the vips package.
-
+=== "Alpine"
-**Alpine (edge)**
+    These instructions apply to the current Edge versions.
     ```sh
     doas apk add git curl msttcorefonts-installer python3 sqlite3 alpine-sdk cmake ffmpeg imagemagick-dev vips-dev font-noto-emoji gobject-introspection-dev cgif-dev libimagequant-dev meson
     ```
-
+=== "Arch/Manjaro"
-**Arch/Manjaro**
     ```sh
     sudo pacman -S git curl cmake pango ffmpeg npm imagemagick libvips sqlite3 libltdl noto-fonts-emoji gobject-introspection libcgif libimagequant meson
     ```
-Arch/Manjaro users: you'll also need to install [`ttf-ms-fonts`](https://aur.archlinux.org/packages/ttf-ms-fonts/) from the AUR.
+    You'll also need to install [`ttf-ms-fonts`](https://aur.archlinux.org/packages/ttf-ms-fonts/) from the AUR.
 
 ***
 
-#### 2. Install libvips.
+### 2. Install libvips.
 
-[libvips](https://github.com/libvips/libvips) is the core of esmBot's image processing commands. The latest version as of writing this (8.12.2) is recommended because it contains fixes to GIF handling; however, there's also a missing feature in this version that is needed for the freeze command to work (see [libvips pull request #2709](https://github.com/libvips/libvips/pull/2709)). To fix this, you'll need to build libvips from source.
+[libvips](https://github.com/libvips/libvips) is the core of esmBot's image processing commands. The latest version (8.13.0) is recommended because it contains fixes to GIF handling and support for the freeze command; however, this version isn't packaged for most distros yet. To fix this, you'll need to build libvips from source.
 
-**Alpine and Arch users can skip this step, since both distros now have 8.13.0 packaged.**
+!!! note
+    Alpine and Arch users can skip this step, since both distros now have 8.13.0 packaged.
 
 First, download the source and move into it:
 ```sh
@@ -64,7 +66,7 @@ sudo meson install
 
 ***
 
-#### 3. Install Node.js.
+### 3. Install Node.js.
 
 Node.js is the runtime that esmBot is built on top of. The bot requires version 15 or above to run.
 
@@ -75,7 +77,7 @@ curl -fsSL https://get.pnpm.io/install.sh | sh -
 
 Once you've done that, continue with the instructions for your operating system below.
 
-**Debian/Ubuntu**  
+=== "Debian/Ubuntu"
     You'll need a more recent version than what's provided in most Debian/Ubuntu-based distros. You can add a repository that contains a supported version by running this command:
     ```sh
     curl -fsSL https://deb.nodesource.com/setup_16.x | sudo bash -
@@ -84,25 +86,22 @@ After that, you can install Node.js with this command:
     ```sh
     sudo apt-get install nodejs
     ```
-
+=== "Fedora/RHEL"
-**Fedora/RHEL**
     ```sh
     sudo dnf install nodejs
     ```
-
+=== "Alpine"
-**Alpine**
     ```sh
     doas apk add nodejs
     ```
-
+=== "Arch/Manjaro"
-**Arch/Manjaro**
     ```sh
     sudo pacman -S nodejs
     ```
 
 ***
 
-#### 4. Set up the database.
+### 4. Set up the database.
 
 esmBot officially supports two database systems: SQLite and PostgreSQL. While SQLite is smaller and requires no initial setup, PostgreSQL has better performance (especially in large environments).
 
@@ -112,7 +111,7 @@ If you would like to use the PostgreSQL database, view the setup instructions [h
 
 ***
 
-#### 5. Clone the repo and install the required Node modules.
+### 5. Clone the repo and install the required Node modules.
 ```sh
 cd ~
 git clone --recurse-submodules https://github.com/esmBot/esmBot
@@ -129,7 +128,7 @@ fc-cache -fv
 
 ***
 
-#### 6. (Optional) Set up Lavalink.
+### 6. (Optional) Set up Lavalink.
 
 Lavalink is the audio server used by esmBot for soundboard commands and music playback. If you do not plan on using these features, you can safely skip this step.
 
@@ -154,17 +153,21 @@ java -Djdk.tls.client.protocols=TLSv1.2 -jar Lavalink.jar
 
 ***
 
-#### 7. Configure the bot.
+### 7. Configure the bot.
 
 Configuration is done via environment variables which can be specified through a `.env` file. Copy `.env.example` to get a starter config file:
 ```sh
 cp .env.example .env
 ```
-If you can't see either of these files, don't worry - Linux treats files whose names start with a . as hidden files. To edit this file in the terminal, run this command:
+
+!!! tip
+    If you can't see either of these files, don't worry - Linux treats files whose names start with a . as hidden files.
+
+To edit this file in the terminal, run this command:
 ```sh
 nano .env
 ```
-This will launch a text editor with the file ready to go. Create a Discord application at https://discord.com/developers/applications and select the Bot tab on the left, then create a bot user. Once you've done this, copy the token it gives you and put it in the `TOKEN` variable.
+This will launch a text editor with the file ready to go. Create a Discord application [here](https://discord.com/developers/applications) and select the Bot tab on the left, then create a bot user. Once you've done this, copy the token it gives you and put it in the `TOKEN` variable.
 
 When you're finished editing the file, press Ctrl + X, then Y and Enter.
 
@@ -172,13 +175,22 @@ An overview of each of the variables in the `.env` file can be found [here](http
 
 ***
 
-#### 8. Run the bot.
+### 8. Run the bot.
 
 Once everything else is set up, you can start the bot like so:
 ```sh
 pnpm start
 ```
-If the bot starts successfully, you're done! You can invite the bot to your server by generating an invite link [here](https://discordapi.com/permissions.html#3533888).
+If the bot starts successfully, you're done! You can invite the bot to your server by generating an invite link under OAuth -> URL Generator in the Discord application dashboard.
+
+!!! note
+    You will need to select the `bot` and `applications.commands` scopes.
+    The following permissions are needed in most cases for the bot to work properly:
+
+    <figure markdown>
+    ![Required permissions](assets/permissions.png){ loading=lazy, width=500 }
+    <figcaption>click to enlarge</figcaption>
+    </figure>
 
 If you want the bot to run 24/7, you can use the [PM2](https://pm2.keymetrics.io) process manager. Install it using the following command:
 ```sh
@@ -190,38 +202,37 @@ Once you've done that, you can start the bot using the following command:
 pm2 start app.js
 ```
 
-***
+!!! tip
-
     If you wish to update the bot to the latest version/commit at any time, just run `git pull` and `pnpm install`.
 
 ***
 
 ## Troubleshooting
-### Error: Cannot find module './build/Release/image.node'
+??? faq "Error: Cannot find module './build/Release/image.node'"
     The native image functions haven't been built. Run `pnpm run build` to build them.
 
-### pnpm fails with error 'ELIFECYCLE  Command failed.'
+??? faq "pnpm fails with error 'ELIFECYCLE  Command failed.'"
-You seem to be missing node-gyp, this can be fixed by running:
+    You seem to be missing node-gyp. This can be fixed by running:
     ```sh
-pnpm -g install node-gyp
+    pnpm i -g node-gyp
-rm -r node_modules
+    rm -rf node_modules
     pnpm install
     ```
 
-### Error: connect ECONNREFUSED 127.0.0.1:5432
+??? faq "Error: connect ECONNREFUSED 127.0.0.1:5432"
     PostgreSQL isn't running, you should be able to start it with `sudo systemctl start postgresql`. If you don't intend to use PostgreSQL, you should take another look at your `DB` variable in the .env file.
 
-### Gifs from Tenor result in a "no decode delegate for this image format" or "improper image header" error
+??? faq "Gifs from Tenor result in a "no decode delegate for this image format" or "improper image header" error"
     Tenor GIFs are actually stored as MP4s, which libvips can't decode most of the time. You'll need to get a Tenor API key from [here](https://developers.google.com/tenor/guides/quickstart) and put it in the `TENOR` variable in .env.
 
-### Emojis are missing in some commands
+??? faq "Emojis are missing in some commands"
     Your system doesn't have an emoji font installed. You can install Google's emoji set with `sudo apt-get install fonts-noto-color-emoji` on Debian/Ubuntu systems, `doas apk add font-noto-emoji` on Alpine, and `sudo pacman -S noto-fonts-emoji` on Arch/Manjaro.
 
     If you want to use the same set that Discord and the main bot uses (Twemoji) on Fedora, then you can run `sudo dnf remove google-noto-emoji-color-fonts && sudo dnf install twitter-twemoji-fonts`.
 
-If you want to install Twemoji on another distro then it's slightly more difficult. Go to https://koji.fedoraproject.org/koji/packageinfo?packageID=26306 and choose the latest build, then download the `noarch` RPM file. You'll then have to extract this file; most graphical tools (e.g. 7-Zip, Ark, The Unarchiver) should be able to extract this just fine, but on the command line you'll have to use the `rpm2cpio` tool. The font file should be inside the archive at `usr/share/fonts/Twemoji/Twemoji.ttf`; copy this to `/usr/share/fonts/Twemoji.ttf` (note the / at the beginning). After this, run `fc-cache -fv` and you should be good to go!
+    If you want to install Twemoji on another distro then it's slightly more difficult. Go [here](https://koji.fedoraproject.org/koji/packageinfo?packageID=26306) and choose the latest build, then download the `noarch` RPM file. You'll then have to extract this file; most graphical tools (e.g. 7-Zip, Ark, The Unarchiver) should be able to extract this just fine, but on the command line you'll have to use the `rpm2cpio` tool. The font file should be inside the archive at `usr/share/fonts/Twemoji/Twemoji.ttf`; copy this to `/usr/share/fonts/Twemoji.ttf` (note the / at the beginning). After this, run `fc-cache -fv` and you should be good to go!
 
-### Sound/music commands do nothing
+??? faq "Sound/music commands do nothing"
     Make sure Lavalink is running and started up completely. The bot skips loading sound commands if Lavalink is not present, so make sure it's running when the bot starts as well.
 
 ***

mkdocs.yml

@@ -0,0 +1,52 @@
+site_name: esmBot
+docs_dir: docs/
+repo_name: 'esmBot/esmBot'
+repo_url: 'https://github.com/esmBot/esmBot'
+copyright: Copyright &copy; 2018 - 2022 <a href="https://essem.space">Essem</a>
+nav:
+    - Home: index.md
+    - setup.md
+    - config.md
+    - custom-commands.md
+    - docker.md
+    - postgresql.md
+markdown_extensions:
+  - def_list
+  - attr_list
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true 
+theme:
+  name: 'material'
+  features:
+    - toc.integrate
+    - content.tabs.link
+  logo: assets/esmbot.png
+  favicon: assets/esmbot.png
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle:
+        icon: material/weather-night
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to light mode
+plugins:
+  - glightbox
+  - git-revision-date-localized:
+      enable_creation_date: true
+extra:
+  social:
+    - icon: fontawesome/brands/twitter 
+      link: https://twitter.com/esmBot_
+    - icon: fontawesome/brands/github
+      link: https://github.com/esmBot
+    - icon: fontawesome/brands/patreon
+      link: https://patreon.com/TheEssem

utils/help.js

@@ -31,7 +31,7 @@ export async function generateList() {
 }
 
 export async function createPage(output) {
-  let template = `# <img src="https://raw.githubusercontent.com/esmBot/esmBot/master/esmbot.png" width="64"> esmBot${process.env.NODE_ENV === "development" ? " Dev" : ""} Command List
+  let template = `# <img src="https://raw.githubusercontent.com/esmBot/esmBot/master/docs/assets/esmbot.png" width="64"> esmBot${process.env.NODE_ENV === "development" ? " Dev" : ""} Command List
 
 This page was last generated on \`${new Date().toString()}\`.