Lint the Markdown files in CI

.github/PULL_REQUEST_TEMPLATE.md

@@ -6,7 +6,8 @@ Before submitting a PR mark the checkboxes for the items you've done (if you
 think a checkbox does not apply, then leave it unchecked):
 
 - [ ] The commits are consistent with our [contribution guidelines][1].
-- [ ] You've added tests (if possible) to cover your change(s). Bugfix, indentation, and font-lock tests are extremely important!
+- [ ] You've added tests (if possible) to cover your change(s). Bugfix, indentation, and font-lock tests
+  are extremely important!
 - [ ] You've run `M-x checkdoc` and fixed any warnings in the code you've written.
 - [ ] You've updated the changelog (if adding/changing user-visible functionality).
 - [ ] You've updated the readme (if adding/changing user-visible functionality).

.github/workflows/ci.yml

@@ -38,3 +38,13 @@ jobs:
 
       - name: Check for byte-compilation errors
         run: eldev -dtT compile --warnings-as-errors
+
+  markdownlint:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: DavidAnson/markdownlint-cli2-action@v24
+        with:
+          globs: '**/*.md'

.markdownlint-cli2.yaml

@@ -0,0 +1,14 @@
+config:
+  default: true
+
+  line-length:
+    line_length: 100
+    code_blocks: false
+    tables: false
+
+  no-duplicate-heading:
+    allow_different_nesting: true
+
+  no-inline-html: false
+
+  first-line-heading: false

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+<!-- Entries are one line per item and section headings repeat for every release,
+     so the line-length and duplicate-heading rules don't fit this file. -->
+<!-- markdownlint-disable MD013 MD024 -->
+
 ## master (unreleased)
 
 ### New features
@@ -361,7 +365,6 @@
 * [#451](https://github.com/clojure-emacs/clojure-mode/issues/451): Make project root directory calculation customized by `clojure-project-root-function`.
 * Fix namespace font-locking: namespaces may also contain non alphanumeric chars.
 
-
 ## 5.6.1 (2016-12-21)
 
 ### Bugs fixed

README.md

@@ -204,7 +204,7 @@ personal config.
 Indent specs use a **modern tuple format** shared with `clojure-ts-mode`:
 
 | Spec | Meaning |
-|------|---------|
+| ---- | ------- |
 | `'((:block N))` | First N args are special, rest indented as body |
 | `'((:inner 0))` | All args indented as body (like `defn`) |
 | `'((:inner D))` | Body-style indent at nesting depth D |
@@ -312,9 +312,11 @@ Backtracking is controlled by `clojure-use-backtracking-indent`
 (default 3).  Disabling backtracking will break indentation for
 all forms with multi-rule specs.
 
-The indentation of [special arguments](https://docs.cider.mx/cider/indent_spec.html#special-arguments) is controlled by
-`clojure-special-arg-indent-factor`, which by default indents special arguments
-a further `lisp-body-indent` when compared to ordinary arguments.
+The indentation of [special
+arguments](https://docs.cider.mx/cider/indent_spec.html#special-arguments) is
+controlled by `clojure-special-arg-indent-factor`, which by default indents
+special arguments a further `lisp-body-indent` when compared to ordinary
+arguments.
 
 An example of the default formatting is:
 
@@ -474,7 +476,7 @@ instructed how to handle the docstrings and highlighting. Here's an example:
 Here's a summary of the keybindings available in `clojure-mode`:
 
 | Keybinding | Command |
-|---|---|
+| --- | --- |
 | `C-c C-a` | `clojure-align` |
 | `C-:` | `clojure-toggle-keyword-string` |
 | `C-c C-r t` | `clojure-thread` |
@@ -518,49 +520,49 @@ to `clojure-mode`.
 `clojure-thread`: Thread another form into the surrounding thread. Both `->>`
 and `->` variants are supported.
 
-<img width="512" src="/doc/clojure-thread.gif">
+<img width="512" src="/doc/clojure-thread.gif" alt="Demo of clojure-thread">
 
 `clojure-unwind`: Unwind a threaded expression. Supports both `->>` and `->`.
 
-<img width="512" src="/doc/clojure-unwind.gif">
+<img width="512" src="/doc/clojure-unwind.gif" alt="Demo of clojure-unwind">
 
 `clojure-thread-first-all`: Introduce the thread first macro (`->`) and rewrite
 the entire form. With a prefix argument do not thread the last form.
 
-<img width="512" src="/doc/clojure-thread-first-all.gif">
+<img width="512" src="/doc/clojure-thread-first-all.gif" alt="Demo of clojure-thread-first-all">
 
 `clojure-thread-last-all`: Introduce the thread last macro and rewrite the
 entire form. With a prefix argument do not thread the last form.
 
-<img width="512" src="/doc/clojure-thread-last-all.gif">
+<img width="512" src="/doc/clojure-thread-last-all.gif" alt="Demo of clojure-thread-last-all">
 
 `clojure-unwind-all`: Fully unwind a threaded expression removing the threading
 macro.
 
-<img width="512" src="/doc/clojure-unwind-all.gif">
+<img width="512" src="/doc/clojure-unwind-all.gif" alt="Demo of clojure-unwind-all">
 
 ### Cycling things
 
 `clojure-cycle-privacy`: Cycle privacy of `def`s or `defn`s. Use metadata
 explicitly with setting `clojure-use-metadata-for-privacy` to `t` for `defn`s
 too.
 
-<img width="512" src="/doc/clojure-cycle-privacy.gif">
+<img width="512" src="/doc/clojure-cycle-privacy.gif" alt="Demo of clojure-cycle-privacy">
 
 `clojure-cycle-not`: Add or remove a `not` form around the current form.
 
-<img width="512" src="/doc/clojure-cycle-not.gif">
+<img width="512" src="/doc/clojure-cycle-not.gif" alt="Demo of clojure-cycle-not">
 
 `clojure-cycle-when`: Find the closest `when` or `when-not` up the syntax tree
 and toggle it.
 
-<img width="512" src="/doc/clojure-cycle-when.gif">
+<img width="512" src="/doc/clojure-cycle-when.gif" alt="Demo of clojure-cycle-when">
 
 `clojure-cycle-if`: Find the closest `if` or `if-not` up the syntax tree and
 toggle it. Also transpose the `else` and `then` branches, keeping the semantics
 the same as before.
 
-<img width="512" src="/doc/clojure-cycle-if.gif">
+<img width="512" src="/doc/clojure-cycle-if.gif" alt="Demo of clojure-cycle-if">
 
 ### Toggle discard forms
 
@@ -607,44 +609,45 @@ Convert any given collection at point to list, quoted list, map, vector or set.
 its binding form with a name provided by the user as a bound name. If called
 with a numeric prefix put the let form Nth level up in the form hierarchy.
 
-<img width="512" src="/doc/clojure-introduce-let.gif">
+<img width="512" src="/doc/clojure-introduce-let.gif" alt="Demo of clojure-introduce-let">
 
 `clojure-move-to-let`: Move the current form to the closest `let`'s binding
 form. Replace all occurrences of the form in the body of the let.
 
-<img width="512" src="/doc/clojure-move-to-let.gif">
+<img width="512" src="/doc/clojure-move-to-let.gif" alt="Demo of clojure-move-to-let">
 
 `clojure-let-forward-slurp-sexp`: Slurp the next form after the `let` into the
 `let`. Replace all occurrences of the bound forms in the form added to the `let`
 form. If called with a prefix argument slurp the next n forms.
 
-<img width="512" src="/doc/clojure-let-forward-slurp-sexp.gif">
+<img width="512" src="/doc/clojure-let-forward-slurp-sexp.gif" alt="Demo of clojure-let-forward-slurp-sexp">
 
 `clojure-let-backward-slurp-sexp`: Slurp the form before the `let` into the
 `let`. Replace all occurrences of the bound forms in the form added to the `let`
 form. If called with a prefix argument slurp the previous n forms.
 
-<img width="512" src="/doc/clojure-let-backward-slurp-sexp.gif">
+<img width="512" src="/doc/clojure-let-backward-slurp-sexp.gif" alt="Demo of clojure-let-backward-slurp-sexp">
 
-`paredit-convolute-sexp` is advised to replace occurrences of bound forms with their bound names when convolute is used on a let form.
+`paredit-convolute-sexp` is advised to replace occurrences of bound forms with
+their bound names when convolute is used on a let form.
 
 ### Rename ns alias
 
 `clojure-rename-ns-alias`: Rename an alias inside a namespace declaration,
 and all of its usages in the buffer
 
-<img width="512" src="/doc/clojure-rename-ns-alias.gif">
+<img width="512" src="/doc/clojure-rename-ns-alias.gif" alt="Demo of clojure-rename-ns-alias">
 
 If there is an active selected region, only rename usages of aliases within the region,
 without affecting the namespace declaration.
 
-<img width="512" src="/doc/clojure-rename-ns-alias-region.gif">
+<img width="512" src="/doc/clojure-rename-ns-alias-region.gif" alt="Demo of clojure-rename-ns-alias-region">
 
 ### Add arity to a function
 
 `clojure-add-arity`: Add a new arity to an existing single-arity or multi-arity function.
 
-<img width="512" src="/doc/clojure-add-arity.gif">
+<img width="512" src="/doc/clojure-add-arity.gif" alt="Demo of clojure-add-arity">
 
 ### Remove unused destructured keys
 
@@ -821,7 +824,7 @@ slow and inaccurate.
 
 ## Changelog
 
-An extensive changelog is available [here](CHANGELOG.md).
+An extensive changelog is available in [CHANGELOG.md](CHANGELOG.md).
 
 ## License