Merge pull request #61 from botlabs-gg/mdl

workflows: add and configure a Markdown linter
all: lint markdown files

.github/CONTRIBUTING.md

@@ -10,7 +10,6 @@ General support queries and possible bugs in YAGPDB are **not** in scope and wil
 
 [support server]: https://discord.gg/4udtcA5
 
-
 ## Submission Guide
 
 Thanks for contributing to the YAGPDB documentation! Please take a moment to review this document in order to make the
@@ -45,7 +44,7 @@ this process below.
 In your local clone, install the required dependencies via NPM by running the following command:
 
 ```shellsession
-$ npm install
+npm install
 ```
 
 This will ensure that you can fully build the documentation site locally, including the custom syntax highlighting we
@@ -117,15 +116,15 @@ In order to preview your changes locally, you will need to run a local instance
 you have Node.js (and NPM) and Hugo installed, you can do so by running the following command:
 
 ```shellsession
-$ npm run dev
+npm run dev
 ```
 
 This will run a local server on `http://localhost:1313` that will automatically update whenever you save a file, though
 without our custom syntax highlighting. If you prefer to view the site as it would appear on production, run the
 following commands instead:
 
 ```shellsession
-$ npm run build && npm run preview
+npm run build && npm run preview
 ```
 
 This will build the site, execute the highlighting post-processor, and run a local server on `http://localhost:4173`.

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,4 +1,5 @@
 <!-- Please describe the changes this pull request does and why it should be merged -->
 
 **Terms**
+
 - [ ] I have read and understood this project's [Contributing Guidelines](CONTRIBUTING.md)

.github/workflows/lint.yml

@@ -0,0 +1,17 @@
+name: Lint
+
+on:
+  pull_request:
+    paths:
+      - 'content/**/*.md'
+
+jobs:
+  lint-markdown:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Lint markdown files
+        uses: actionshub/markdownlint@main
+        with:
+          filesToIgnoreRegex: 'all-commands.md|scripts/.*|.github/.*'

.mdlrc

@@ -0,0 +1,3 @@
+git_recurse true
+ignore_front_matter true
+style 'config/markdownlint.rb'

README.md

@@ -26,8 +26,9 @@ Pages are written in Markdown with additional shortcodes provided by the Doks th
 documentation](<(https://getdoks.org/docs/start-here/getting-started/)>) for a complete list of features.
 
 If you are editing pages related to custom commands, note that codeblocks support a custom `yag` language for accurate
-syntax highlighting—do not use `go`. However, this feature is only enabled in production builds for performance, so `npm run dev` will _not_ highlight `yag` codeblocks. Use `npm run build` followed by `npm run preview` instead if you need to verify
-that code is highlighted correctly.
+syntax highlighting—do not use `go`. However, this feature is only enabled in production builds for performance, so
+`npm run dev` will _not_ highlight `yag` codeblocks. Use `npm run build` followed by `npm run preview` instead if you
+need to verify that code is highlighted correctly.
 
 > [!TIP]
 > If you use VSCode, this project provides custom workspace snippets to insert callouts, which you can activate in

config/markdownlint.rb

@@ -0,0 +1,49 @@
+# Enable all rules; we'll configure some of them below.
+all
+
+# MD001: Header levels should only increment by one level at a time.
+# Normally, this is a fair rule, but it does not quite work for our cases,
+# especially in our humongous functions list. So disable it.
+exclude_rule 'MD001'
+
+# MD002: First header should be a top level header.
+# Some files do not have a top-level header, because it doesn't make sense for
+# them, or just looks incredibly stupid on the rendered page. So disable this
+# entire rule.
+exclude_rule 'MD002'
+
+# MD004: Unordered list style.
+# Use dashes for unordered lists. All lists. Even sublists.
+rule 'MD004', :style => :dash
+
+# MD013: Line length.
+# Allow lines to be up to 120 characters long, see the .editorconfig file.
+# We also ignore code blocks, because they are often long and should not be
+# wrapped at all. Same goes for tables.
+rule 'MD013', :line_length => 120, :ignore_code_blocks => true, :tables => false
+
+# MD024: Multiple headers with the same content.
+# Allow multiple headers with the same content so long they are under different
+# parent headers.
+rule 'MD024', :allow_different_nesting => true
+
+# MD026: Trailling punctuation in header.
+# Allow question marks (FAQ-style).
+rule 'MD026', :punctuation => '.,;:!'
+
+# MD029: Ordered list item prefix.
+# Should increase in numerical order.
+rule 'MD029', :style => :ordered
+
+# MD033: Inline HTML.
+# Allow certain HTML elements, because we use them for nicer page layout.
+rule 'MD033', :allowed_elements => 'center, div, sup, br, kbd'
+
+# MD037: Spaces inside emphasis markers.
+# This rule is broken. See https://github.com/markdownlint/markdownlint/issues/84
+exclude_rule 'MD037'
+
+# MD041: First line in file should be a top-level header.
+# See comment to MD002. It makes no sense to set this to H2 for similar reasons,
+# we have TOML frontmatter with an automatic h1 in the rendered page.
+exclude_rule 'MD041'

content/discord.md

@@ -1,7 +1,11 @@
-+++
-type = "redirect"
-target = "https://discord.gg/4udtcA5"
-title = "Discord"
-+++
+---
+type: redirect
+target: 'https://discord.gg/4udtcA5'
+title: 'Discord'
+---
 
-<!-- this file intentionally left blank -->
+<!--
+This file intentionally left blank.
+We use YAML front matter here instead of the usual TOML just so markdownlint can properly lint for blank URLs in other
+files without firing on this one.
+-->

content/docs/core/command-settings.md

@@ -39,7 +39,7 @@ Flags and switches are **_not_** affected by your prefix setting.
 
 For example, if your prefix is `?`, a command usage with flags and/or switches is as follows:
 
-```
+```txt
 ?wouldyourather -raw
 ```
 

content/docs/custom-commands/commands.md

@@ -283,13 +283,13 @@ You must specify a channel to run time-based commands in even if the command doe
 
 A cron expression represents a set of times, using 5 space-separated fields.
 
-Field name       | Mandatory? | Allowed values  | Allowed special characters
---------------   | ---------- | --------------  | --------------------------
-Minutes          | Yes        | 0-59            | * / , -
-Hours            | Yes        | 0-23            | * / , -
-Day of month     | Yes        | 1-31            | * / , - ?
-Month            | Yes        | 1-12 or JAN-DEC | * / , -
-Day of week (DOW)| Yes        | 0-6 or SUN-SAT  | * / , - ?
+| Field name       | Mandatory? | Allowed values  | Allowed special characters |
+| --------------   | ---------- | --------------  | -------------------------- |
+| Minutes          | Yes        | 0-59            | * / , -                    |
+| Hours            | Yes        | 0-23            | * / , -                    |
+| Day of month     | Yes        | 1-31            | * / , - ?                  |
+| Month            | Yes        | 1-12 or JAN-DEC | * / , -                    |
+| Day of week (DOW)| Yes        | 0-6 or SUN-SAT  | * / , - ?                  |
 
 To read more about the supported format of cron expressions, visit [Robfig's Cron package documentation - Expression
 Format](https://pkg.go.dev/github.com/robfig/cron/v3#hdr-CRON_Expression_Format).
@@ -302,7 +302,7 @@ on Corntab Guru, but are not supported with YAGPDB.
 
 {{< /callout >}}
 
-**Special Characters**
+###### Special Characters
 
 - Asterisk ( * )
 

content/docs/fun/soundboard.md

@@ -32,7 +32,6 @@ Do **not** fill in the URL if you are going uploaded from local files, and vice
 
 {{< /callout >}}
 
-
 You have two options to upload sounds:
 
 - Upload with local files

content/docs/moderation/advanced-automoderator/triggers.md

@@ -156,7 +156,6 @@ This trigger will fire when a message matches the specified regular expression.[
 - **Also match visually similar characters**<br>
     Whether to also match visually similar characters, like `Ĥéĺĺó`. (Default: off)
 
-
 #### Message not matching Regex
 
 The inverse of [Message matches Regex](#message-matches-regex). See there for configuration.
@@ -305,12 +304,11 @@ This trigger will fire when a message triggers Discord's Automod.
 
 <!-- footnotes -->
 
-[^1]: The regular expression used to match links is the following:
-<code>(?i)([a-z\d]+://)([\w_-]+(?:(?:\.[\w_-]+)+))([\w.,@?^=%&:/~+#-]*[\w@?^=%&/~+#-])</code>
+[^1]: The regular expression used to match links is the following:<br>
+``(?i)([a-z\d]+://)([\w_-]+(?:(?:\.[\w_-]+)+))([\w.,@?^=%&:/~+#-]*[\w@?^=%&/~+#-])``
 
 [^2]: Under the hood, the bot will only check the last 1000 messages in the channel. If you have a high-traffic channel
 in combination with an extremely long time frame, the bot could (theoretically) miss some messages.
 
 [^3]: The RegEx engine used in YAGPDB is RE2. Some features are not supported, like lookaheads and lookbehinds. See
     [regex101](https://regex101.com/?flavor=golang) for some help with writing RE2-compatible regular expressions.
-

content/docs/moderation/moderation-tools.md

@@ -112,23 +112,30 @@ To remove the requirement and make the reason optional, you may toggle this on (
 
 #### Moderation DMs
 
-Moderation DMs are template scripts (**3**) which are executed within the offending user's DM. Text output to the response will
-be directly sent to the offending user.
+Moderation DMs are template scripts (**3**) which are executed within the offending user's DM. Text output to the
+response will be directly sent to the offending user.
 
 {{< link-card href="/docs/reference/templates/syntax-and-data" description="Templates Reference" target="_blank" >}}
 
 Additional template dot context data is available for Moderation Actions:
 
 - `{{.Reason}}`: The reason specified in the timeout.
-- `{{.Author}}`: The author of the punishment, is a [user object](/docs/reference/templates/syntax-and-data#user).
-- `{{.Duration}}`: The duration of the mod action as a [time.Duration format](/docs/reference/templates/syntax-and-data#time).
+- `{{.Author}}`: The author of the punishment, is a [user object].
+- `{{.Duration}}`: The duration of the mod action as a [time.Duration format].
 - `{{.HumanDuration}}`: The duration in a human friendly format (`1 hour and 3 minutes` for example).
 - `{{.WarningID}}`: The ID of the warning (when using the warn command).
 
+[user object]: /docs/reference/templates/syntax-and-data#user
+[time.Duration format]: /docs/reference/templates/syntax-and-data#time
+
+{{< callout context="danger" title="Danger: Template Execution Errors" icon="outline/alert-octagon" >}}
+
 Any errors which occur in the template execution will not be logged by default. The offending user will only receive a
 DM from your server saying **Failed executing template.** Setting a [Moderation DM Error channel](#mod-channels) allows
 for the more detailed errors to be captured.
 
+{{< /callout >}}
+
 Moderation actions which send DMs are:
 
 - Timeout
@@ -273,8 +280,8 @@ You may optionally send warnings to the mod log, this is enabled in the warnings
 
 [ClearWarnings Command Syntax](/docs/core/all-commands#clearwarnings) - Clears the warnings of a user.
 
-[TopWarnings Command Syntax](/docs/core/all-commands#topwarnings) - Shows ranked list of warnings on the server, allowing you to turn
-misbehavior into a fun minigame for your server members.
+[TopWarnings Command Syntax](/docs/core/all-commands#topwarnings) - Shows ranked list of warnings on the server,
+allowing you to turn misbehavior into a fun minigame for your server members.
 
 {{< callout context="tip" title="Tip: Taking Action on Warn Count" icon="outline/rocket" >}}
 

content/docs/notifications/streaming.md

@@ -6,7 +6,6 @@ description = "Spam your server with notifications when someone starts streaming
 
 Let everyone know that someone is currently streaming.
 
-
 ### Streaming Feed
 
 {{< callout context="note" title="Note: Announcements may not Post" icon="outline/info-circle" >}}

content/docs/notifications/youtube.md

@@ -24,18 +24,17 @@ may need to scroll down a bit); then select a channel to post it to. For a visua
 
 </center>
 
-
 If you are unable to obtain a direct channel URL, similar to<br>
-*https://youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw*, we also support the following URLs:
+*<https://youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw>*, we also support the following URLs:
 
-- Video links (https://youtube.com/watch?v=dQw4w9WgXcQ)
-- Shorts links (https://youtube.com/shorts/pBZ_2pX_8mg)
-- Share links (https://youtu.be/dQw4w9WgXcQ)
-- Live links (https://youtube.com/live/jfKfPfyJRdk)
-- Playlist links (https://youtube.com/playlist?list=PLEamUZtdyTMxwDNQ97Y7im8EwqRyht12R)
+- Video links (<https://youtube.com/watch?v=dQw4w9WgXcQ>)
+- Shorts links (<https://youtube.com/shorts/pBZ_2pX_8mg>)
+- Share links (<https://youtu.be/dQw4w9WgXcQ>)
+- Live links (<https://youtube.com/live/jfKfPfyJRdk>)
+- Playlist links (<https://youtube.com/playlist?list=PLEamUZtdyTMxwDNQ97Y7im8EwqRyht12R>)
 
-Although we make an attempt at extracting the channel from usernames (https://youtube.com/user/MontyPython),
-custom links (https://youtube.com/c/Taskmaster), and handles (https://youtube.com/@TomScottGo), these are not as
+Although we make an attempt at extracting the channel from usernames (<https://youtube.com/user/MontyPython>),
+custom links (<https://youtube.com/c/Taskmaster>), and handles (<https://youtube.com/@TomScottGo>), these are not as
 reliable as the links listed above, as we use the first result of a YouTube search to determine the channel via these
 URLs.
 

content/docs/reference/custom-command-examples.md

@@ -221,7 +221,7 @@ You don't have any notes :(
 {{end}}
 ```
 
-### Cooldown Example 
+### Cooldown Example
 
 With YAGPDB's database system, you can now add cooldowns to you custom commands. You can either make them global
 cooldowns or a per user cooldown.