Merge pull request #61 from botlabs-gg/mdl

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

Author: l-zeuch

.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