Add markdownlint pre-commit

.markdownlint.yaml

@@ -0,0 +1,14 @@
+default: true
+MD007: # Unordered list indentation
+  indent: 4
+MD013: false # Line length
+MD029: # Ordered list item prefix
+  style: one_or_ordered
+MD033: # Inline HTML
+  allowed_elements:
+  - a
+MD036: false # Emphasis used instead of a header
+MD040: false # Fenced code blocks should have a language specified
+MD041: false # First line in file should be a top level header
+no-hard-tabs: true 
+whitespace: true 

.pre-commit-config.yaml

@@ -0,0 +1,5 @@
+repos:
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: v0.35.0
+    hooks:
+    - id: markdownlint-fix

README.md

@@ -1,4 +1,4 @@
-# [Visit the Swizzin website here](https://swizzin.ltd)
+## [Visit the Swizzin website here](https://swizzin.ltd)
 
 ----
 

docs/dev/beta-testing.md

@@ -55,4 +55,5 @@ All you need to do is run `box update`, and you will be back right on track!
 If you are unsure what is safe to do, please ask the author of the branch to provide you with instructions on how to get back.
 
 ### Preventing updates
+
 If you'd like to make sure that you do not go back to the master branch until you are ready, please read the [section on updating](/dev/setup#updating-mechanism).

docs/dev/functions.md

@@ -5,11 +5,13 @@ sidebar_label: Functions
 ---
 
 ## Snippets
+
 We are keeping a lot of reusable code in the `.vscode/*.code-snippets` files.
 
 These give you auto-completions within VSCode and its derivatives, and have pre-defined fields which you can tab-through in order to skip to the next ones.
 
 There _should_ be snippets available for all of the functions declared in `global.sh`.
+
 ## Functions
 
 :::caution Work in progress!
@@ -29,6 +31,7 @@ These functions provide a solution to storing arbitrary information organised by
 The keys can contain slashes in order to define further structure to the database, in a smilar fashion Windows uses registry keys. Therefore, `abc/def` will create a directory called `abc` and store the key `def` in it. You can then retrieve that value under the key `abc/def`.
 
 Available functions are:
+
 - `swizdb set $key $value`
     - Stores the content of `$value` under the `$key`
 - `swizdb get $key`
@@ -41,36 +44,41 @@ Available functions are:
     - Removes the key and clears its stored value from the filesystem
     - Returns exit code `1` in case the key is not present
 - `swizdb list [$key]`
-    - Returns a list of present and set full keys 
+    - Returns a list of present and set full keys
     - Can filter results based on a key "directory".
 
 #### `os` functions
+
 _Documented in the file itself_
 
 #### `user` functions
-_Documented in the file itself_
 
+_Documented in the file itself_
 
 #### Echo functions
-_Documented in Contributors.md_
 
+_Documented in Contributors.md_
 
 #### Apt functions
+
 _Documented in Contributors.md_
 
 ### Functions that need to be `source`d
 
 #### `utils`
+
 This file contains various functionality which is difficult to separate or justify an entire file for. It is **not** included in `globals.sh` by default.
 
 Functions can be moved out of this file and split into their own if it makes sense, but that's a really loose definition and is usually discussed at PR-level. Obviously, if that happens, corrective action needs to be done wherever the functions were used, and the scripts that use it should vaguely be re-tested.
 
 #### Python functions for `pyenv` and `venv`
+
 _Documented inline_
 
 These functions handle the installation of the required python versions and creating virtual environments for applications. Please refer to the existing use of these functions in source code.
 
 #### `tests`
+
 _Documented **thoroughly** inline_
 
-This file contains small tests which will often attempt to guess at best testing values unless supplied (e.g. ports, or baseurls). Please read the inline documentation thoroughly.
+This file contains small tests which will often attempt to guess at best testing values unless supplied (e.g. ports, or baseurls). Please read the inline documentation thoroughly.

docs/dev/intro.md

@@ -12,4 +12,4 @@ These docs tell you how to get easily started with a setup we know is fast, conv
 
 :::caution These docs are in progress!
 While this chapter is in development, please make sure to still refer to the [CONTRIBUTORS.md](https://github.com/swizzin/swizzin/blob/master/CONTRIBUTING.md) on our GitHub, which has a very condensed version of all of this.
-:::
+:::

docs/dev/setup.md

@@ -5,24 +5,28 @@ sidebar_label: Setup
 ---
 
 ## VM
+
 We highly suggest you use a virtualized environment to test your swizzin set up. It is extremely convenient to have this isolated from the rest of your system, and be able to discard and initialize a system within minutes.
 
 ### Multipass
+
 :::tip Sausage's preferred development setup
 :::
+
 1. Enable virtualization OS and BIOS side
 1. [Install multipass](https://multipass.run)
-1. Run `multipass shell` to start a default primary VM and join the shell. 
-2. Get swizzin repo on your VM
+1. Run `multipass shell` to start a default primary VM and join the shell.
+1. Get swizzin repo on your VM
    1. You can mount it wherever you want (your user directory should be auto-mounted into `/home/ubuntu` if you're using the `primary` instance)
    2. You can clone it wherever you want
-3. Install swizzin with `bash /path/to/setup.sh --local`
+1. Install swizzin with `bash /path/to/setup.sh --local`
 
 ### LXD
 
 **TODO**
 
 ### Parallels
+
 1. Download your image
 2. Create a VM
 3. Run through the OS install
@@ -47,37 +51,41 @@ Please see contributors.md in the main repo while this is under development
 
 ## Installation
 
-This will install swizzin and as part of the setup, symlink your folder to `/etc/swizzin/`. This is useful if your virtualization auto-mounts from your host. 
+This will install swizzin and as part of the setup, symlink your folder to `/etc/swizzin/`. This is useful if your virtualization auto-mounts from your host.
+
 ```bash
 bash /path/to/setup.sh --local
 ```
 
 You can also already have the swizzin folder mounted/cloned in `/etc/`, this option will switch to use the `.dev.lock` option. This is useful if you're manually mounting the folder from your host, or have cloned directly into your VM.
+
 ```bash
 bash /etc/swizzin/setup.sh --local
 ```
+
 ### Updating mechanism
+
 The updater will always reset `/etc/swizzin` to the latest commit in `master`, which you don't necessarily always want.
 
 We have made a couple ways to make sure that you can skip that, so that you can then manipulate the content of the directory on your own.
 
-*  Running `box update --local`
-*  Making `/etc/swizzin` a symlink to some other directory on your FS
-   *  This should be done for you if you ran `setup.sh` when it was located outside of `/etc/swizzin` with `--local`
-*  Adding `.dev.lock` to `/etc/swizzin/`
-   *  This should be done for you if you ran `setup.sh` when it was located in `/etc/swizzin` with `--local`
-   *  You can do `touch /etc/swizzin/.dev.lock`
-
+* Running `box update --local`
+* Making `/etc/swizzin` a symlink to some other directory on your FS
+    * This should be done for you if you ran `setup.sh` when it was located outside of `/etc/swizzin` with `--local`
+* Adding `.dev.lock` to `/etc/swizzin/`
+    * This should be done for you if you ran `setup.sh` when it was located in `/etc/swizzin` with `--local`
+    * You can do `touch /etc/swizzin/.dev.lock`
 
 ## Testing mechanism
+
 You can run `box test` to test whether all packages are performing as intended. You can supply a specific set of packages (e.g. `box test app1 app2`) to test specifically those.
 
 If you create  `.test.lock` in `/etc/swizzin`, the test will be performed on every applicable `box` command executed (package and user management ones)
 
-
 ## Working across forks
+
 If you need a branch from someplace else, please use the GitHub CLI tool `gh`
 
 You can read how to install and use the tool on the [GitHub CLI website](https://cli.github.com/).
 
-You can then just run `gh pr checkout 401` to checkout PR #401
+You can then just run `gh pr checkout 401` to checkout PR #401

docs/dev/structure.md

@@ -11,48 +11,53 @@ This sub-chapter goes over what each of the folders in swizzin contains, why the
 A lot of swizzin logic **depends** on lockfiles and script files following a naming convention. Scripts will be called `<app>.sh` and their lockfiles will be called `/install/.<app>.lock`. This means that the naming of these **must** stay in sync in order for swizzin to function correctly. Plase bare this in mind. Exceptions to this rule are explained in the chapters where they apply.
 
 ## Scripts
+
 These scripts are to be called directly from their respective `box` calls. Each category is expected to follow the same general structure.
 
 **Please familiarise yourself with the "rules of thumb" of the code that is present around the code you are making.**
 
 ### Install
+
 `scripts/install/`
 
 This directory contains the script that will be executed when `box install <app>` is executed, which will directly invoke `scripts/install/<app>.sh`.
 
 The script should generally do the following, if it applies.
 
 - Gathering information from the user required for installation
-  - Please make sure to expose an option to skip these through defining environment variables to provide the answers, and checking their presence. These will need to also be documented.
+    - Please make sure to expose an option to skip these through defining environment variables to provide the answers, and checking their presence. These will need to also be documented.
 - Checking incompatibilities
-  - Possibly migrate from previous major versions/forks of the same application, such as Sonarr v2 -> v3.
+    - Possibly migrate from previous major versions/forks of the same application, such as Sonarr v2 -> v3.
 - Installing dependencies
 - Installing the application (through `apt`, a binary or a script)
 - Handling user addition in case the app is Multi-user compatible.
 - Creating and starting the `systemd` service
 - Installing an nginx config for the application
-  - _Note: Please make sure to print the application's port to the user when nginx is not installed!_
+    - _Note: Please make sure to print the application's port to the user when nginx is not installed!_
 - **Creating the lock for the application**
 
 It is _heavily_ encouraged to compartmentalise your code into bash functions which are then executed in sequence at the bottom of the file. This provides a better visual segmentation of the code, as well as a better semantic separation which helps with maintenance.
 
 ### Test
+
 This dir contains logic to run when `box test [app]*` is executed directly, or indirectly after some `box` commands while on "unstable" or "development" installs.
 
 **Unless a file for the specific application is present in this directory**, the default test is ran with the application's name passed to it.
 
 Generally, a testing scenario (be it via the default script or the ad-hoc script) should achieve the following:
+
 - Check if services are running
 - Check if the application has open ports on the local network (e.g. checking port `8080` is open and being listened to)
 - Check if the port is responding to HTTP requests (e.g. checking `localhost:56789`)
 - Check if the application is accessible via the reverse proxy (e.g. `localhost/deluge`)
-  - This should include an authentication to the proxy unless the authentication is outside of nginx's control
+    - This should include an authentication to the proxy unless the authentication is outside of nginx's control
 - Any additional functional test to verify that the system is responding correctly
-  - e.g. if the system user is able to read/write into a user's directory
+    - e.g. if the system user is able to read/write into a user's directory
 
 There are cases when no tests really apply (e.g. `ffmpeg`), and so a "dummy" test file can be required in some instances.
 
 ### Remove
+
 `scripts/remove/`
 This directory contains the script that will be executed when `box remove <app>` is executed, which will directly invoke `scripts/remove/<app>.sh`
 
@@ -63,14 +68,16 @@ The script should generally do the following, if it applies.
 - Remove application files (e.g. from `/opt`)
 - **Removing the lock for the application**
 
-**Please note**: Removing the application's user data/config is something we are currently debating and assessing on a per-application basis. 
+**Please note**: Removing the application's user data/config is something we are currently debating and assessing on a per-application basis.
 
 ### Nginx
+
 `scripts/nginx/`
 
 This directory holds scripts that enable an application to work with the `nginx` reverse proxy.
 
 There are two times this can be triggered, so please take that into account when writing these scripts
+
 - When nginx is already installed and an application is being installed via `box install app`
 - After an application is already installed and `nginx` is being via `box install nginx`
 
@@ -79,38 +86,42 @@ This means that all changes to an app's configuration which is require for the r
 **Handle the nginx reload outside of these scripts**. If you add nginx reloads, this would mean that while the `nginx` installer is running, it will have to reload after every config is installed, which is a bit unnecessary.
 
 ### Upgrade
+
 `scripts/upgrade/`
 
 This directory contains the script that will be executed when `box upgrade <app>` is executed, which will directly invoke `scripts/upgrade/<app>.sh`
 
 The aim of the scripts in here is to ensure that applications get upgraded across versions when one of the following scenarios is true
+
 - Application is **not** managed through the `apt` package manager
-  - e.g. `lounge` is installed via `npm`
+    - e.g. `lounge` is installed via `npm`
 - There is not built in updater in the application
-  - e.g. `lounge` has no "update" button in the application itself
-  - however `radarr` has a built-in self-updater, so no `upgrade` script is necessary
+    - e.g. `lounge` has no "update" button in the application itself
+    - however `radarr` has a built-in self-updater, so no `upgrade` script is necessary
 - A new major version needs to be opted-in by the user
-  - e.g. the Sonarr v2 to Sonarr v3 migration has to be made by user's choice, and additional functionality needs to be executed to complete a succesful migration between the version.
+    - e.g. the Sonarr v2 to Sonarr v3 migration has to be made by user's choice, and additional functionality needs to be executed to complete a succesful migration between the version.
 
 Before any of the upgrade scripts are ran, the `box update` procedure is done.
 
 ### Update
+
 `scripts/update/`
 
 These scripts intend to make sure that the user's installation is up to spec with what we expect in our code, so that we do not need to keep track of all the different changes and the history of the package in all the scripts above.
 
 **All scripts in this directory will be executed in alphabetical order when `box update` is ran**. It is therefore required that scripts here have their "main functionality" wrapped in `if` statements which verify if the script should run.
 
 Each update statement is required to have the following implemented:
+
 - Conditional checks whether execution is necessary (exceptions apply, but discussed at PR-time)
-  - In general, this would usually consist of:
+    - In general, this would usually consist of:
     1. Top-level check for whether an application is installed
     2. Per-segment check whether the conditions for the update are present
 - A comment describing the condition for the update to trigger
-  - Any further context should be provided 
+    - Any further context should be provided
 - Handled echos
-  - `echo_info` for the start of an update segment and `echo_success` at the end of it
-  - An `echo_log` in case the update is being skipped. 
+    - `echo_info` for the start of an update segment and `echo_success` at the end of it
+    - An `echo_log` in case the update is being skipped.
 
 These scripts are meant to ensure that older installations behave the exact same way that a fresh installation would. They do not upgrade packages themselves at all. They are purely maintenance scripts ran to update the installation.
 
@@ -124,20 +135,23 @@ While not exactly kosher, you _can_ use this folder for other scripts that shoul
 -->
 
 ## Sources
+
 `sources`
 
 This directory contains a lot of helper scripts in general.
 
 You can read what each of these functions does in the [functions chapter](functions.md)
 
 ### `globals.sh`
+
 Contains the sourcing of all the functions that are "taken for granted" in all the scripts above.
 
 This script gets ran as the first thing when `box` functions are triggered, and when running the `setup.sh`. In case you're running `box`-less, you will need to source this into your shell before running your scripts.
 
 All of the files mentioned in this file **must** have their functions and variables `export`ed so that they are accessible in the parent shell.
 
 ### Functions
+
 `sources/functions`
 
 This directory contains all reusable helper functions. All the files within here are expected to be `source`d (often done via the bash `.` alias). This means that all the files here should **only** contain functions which are re-used later, and that these files do not execute anything when being sourced.