Add Markdown linting to CI (hellt#19)

* Surround md headers with spacing to resolve MD022

* Resolve several markdown warnings in README.md

  * line length MD013
  * lists surrounded by blank lines MD032
  * bare URL MD034

* Resolve curl long line MD013 in README.md

* Add step to Codespace method in README.md

* Resolve markdown line length MD013

* Add newline to output to appease markdownlint MD047

* Resolve more long lines in README.md

* Resolve linting issues in CONTRIBUTING.md

* headers surrounded by blank lines MD022
* long lines MD013
* changing long lines manifested MD032
* changed unordered to ordered list in Dev section MD007

* Remove inline HTML/image to lint README.md

* long line warning
* inline HTML warning

* Change "a first" to "the first" in README.md

* Resolve bare URLs - MD034

* Add Node.js packages directory to .gitignore

* Fix string format to use double quotes

* Add markdownlint-cli2 config

* Add npm (Node.js) packaging for markdownlint-cli2

* Add markdown linting Action to cicd.yml

* Update cicd.yml - test depends on mdlint

* Fix mdlint path for test files in cicd.yml

* Update goal comment in cicd.yml

* Revert "Add Node.js packages directory to .gitignore"

This reverts commit 84fc5b0.

* Revert "Add npm (Node.js) packaging for markdownlint-cli2"

This reverts commit 722977c.

* Move file globbing to .markdownlint-cli2.yaml

Author: mjbear

.github/workflows/cicd.yml

@@ -11,14 +11,16 @@ on:
     types: ["created"]
 
 # GOAL:
-#  - run ruff job on pushes to main branch or v* tag
-#  - run ruff job on PRs against main branch
-#  - run ruff job on Release creation
-#  - run test job on pushes to main branch or v* tag
-#  - run test job on PRs against main branch
-#  - run test job on Release creation
-#  - run docker job on the above events when the triggered actor is the repo owner
-#  - run docker job on Release creation (ex: maybe a maintainer that isn't repo owner)
+#  on pushes to main branch or v* tag
+#    - ruff, mdlint, test
+#  on PRs against main branch
+#    - ruff, mdlint, test
+#  on Release creation
+#    - ruff, mdlint, test
+#  on the above events when the triggered actor is the repo owner
+#    - docker
+#  on Release creation (ex: maybe a maintainer that isn't repo owner)
+#    - docker
 
 jobs:
   ruff:
@@ -39,10 +41,21 @@ jobs:
           args: "format --check --diff"
           changed-files: "true"
 
+  mdlint:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Check out repository code
+      uses: actions/checkout@v4
+    
+    - name: Run markdownlint-cli2
+      uses: DavidAnson/markdownlint-cli2-action@v17
+      # file globbing configured in .markdownlint-cli2.yaml
+
   test:
     runs-on: ubuntu-latest
     needs:
       - "ruff"
+      - "mdlint"
     strategy:
       matrix:
         python-version: ["3.9", "3.10", "3.11", "3.12"]

.markdownlint-cli2.yaml

@@ -0,0 +1,9 @@
+---
+default: true
+
+config:
+
+globs:
+  - '*.{md,markdown}'
+  - 'tests/*/*.{md,markdown}'
+...

CONTRIBUTING.md

@@ -4,11 +4,19 @@
 
 A couple of quick items:
 
-1. To avoid duplicate issues and PRs, [please search open issue and pull requests](https://docs.github.com/en/issues/tracking-your-work-with-issues/filtering-and-searching-issues-and-pull-requests) before submitting a new one.
-1. The general expectation is to [submit a GitHub issue](https://help.github.com/en/github/managing-your-work-on-github/creating-an-issue) to receive feedback before submitting a pull request (PR) with changes.
+1. To avoid duplicate issues and PRs, [please search open issue and pull requests](https://docs.github.com/en/issues/tracking-your-work-with-issues/filtering-and-searching-issues-and-pull-requests)
+   before submitting a new one.
+
+1. The general expectation is to [submit a GitHub issue](https://help.github.com/en/github/managing-your-work-on-github/creating-an-issue)
+   to receive feedback before submitting a pull request (PR) with changes.
+
     * _This will help ensure ideas align with the project scope._
-1. Unit tests should accompany [Pull Requests (PRs)](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) **whenever possible**. :point_left:
-    * This could mean adding additional tests to an existing unit test file or creating a new one.
+
+1. Unit tests should accompany [Pull Requests (PRs)](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests)
+   **whenever possible**. :point_left:
+
+    * This could mean adding additional tests to an existing unit test file or
+      creating a new one.
 
 ## Ways to Contribute
 
@@ -21,23 +29,38 @@ A couple of quick items:
 
 ## Testing Framework
 
-For minimal dependencies, the "batteries included" [Python `unittest` framework](https://docs.python.org/3/library/unittest.html) is utilized. (Other testing frameworks could be considered should additional testing features be needed.)
+For minimal dependencies, the "batteries included" [Python `unittest` framework](https://docs.python.org/3/library/unittest.html)
+is utilized. (Other testing frameworks could be considered should additional
+testing features be needed.)
 
 ## Development Process
+
 >
 > This section consists of suggestions.
 
-It is recommended to verify tests are successful before making any code changes. From there make your changes and run the unit tests to validate there is not code regression.
+It is recommended to verify tests are successful before making any code changes.
+From there make your changes and run the unit tests to validate there is not
+code regression.
+
+1. [Create a fork of this project](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo)
+
+    * If you have an existing fork of this project be sure [to synchronize it](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork)!
+
+1. From the `main` branch of your fork, [create a feature branch](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository)
 
-* [Create a fork of this project](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo)
-  * If you have an existing fork of this project be sure [to synchronize it](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork)!
-* From the `main` branch of your fork, [create a feature branch](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository)
-* Validate [test cases run successfully](#running-unit-tests) before any changes are made
-* Make modifications
-* Re-test with the existing unit tests against the modified codebase
-* Add any additional unit tests to improve testing coverage
-* Re-run the unit tests to confirm they run successfully
-* When you are satisfied with the changes and it is ready for review, [submit a Pull Request (PR)](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request)
+1. Validate [test cases run successfully](#running-unit-tests) before any
+  changes are made
+
+1. Make modifications
+
+1. Re-test with the existing unit tests against the modified codebase
+
+1. Add any additional unit tests to improve testing coverage
+
+1. Re-run the unit tests to confirm they run successfully
+
+1. When you are satisfied with the changes and it is ready for review,
+  [submit a Pull Request (PR)](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request)
 
 ## Running Unit Tests
 
@@ -47,12 +70,16 @@ Choose one of the below testing commands methods that suits your needs.
 > The commands below are to be run from the top level of the project.
 
 1. Discover and run unit tests
+
     * `python -m unittest discover`
 
 1. Verbose version of unit test discovery
+
     * `python -m unittest discover -v`
 
 1. Discover unit tests in specific directory (in this case, `tests`) with verbosity
+
     * `python -m unittest discover -s tests -v`
 
-:bulb: For additional `unittest` command line options, refer to the [official Python unittest documentation](https://docs.python.org/3/library/unittest.html#command-line-interface).
+:bulb: For additional `unittest` command line options, refer to the
+[official Python unittest documentation](https://docs.python.org/3/library/unittest.html#command-line-interface).

README.md

@@ -2,7 +2,7 @@
 
 A script to sort footnotes in a markdown file.
 
-Reads a Markdown file passed as a first argument and sorts footnotes.
+Reads a Markdown file passed as the first argument and sorts footnotes.
 The reference links will be numbered in
 the order they appear in the text and placed at the bottom
 of the file.
@@ -11,11 +11,7 @@ Based on <https://github.com/derdennis/sort-markdown-footnotes>
 
 Inspired by <http://www.leancrew.com/all-this/2012/09/tidying-markdown-reference-links/>
 
-
-
-https://github.com/user-attachments/assets/2ccb1782-1d85-499c-ba09-3be94c34a591
-
-
+[Example video](https://github.com/user-attachments/assets/2ccb1782-1d85-499c-ba09-3be94c34a591)
 
 ## How to use?
 
@@ -28,37 +24,55 @@ https://github.com/user-attachments/assets/2ccb1782-1d85-499c-ba09-3be94c34a591
 1. Or download the script and put it in your `$PATH`:
 
     ```bash
-    curl -sL https://raw.githubusercontent.com/hellt/markdown-footnote-sorter/main/fnsort.py \
+    curl -sL \
+    https://raw.githubusercontent.com/hellt/markdown-footnote-sorter/main/fnsort.py\
       > ~/.local/bin/fnsort.py
 
     fnsort.py path/to/doc.md
     ```
 
-1. Or run the container in a [Codespace](https://docs.github.com/en/codespaces/overview):sparkles: via the GitHub UI:
+1. Or from the GitHub UI, run the container in a :sparkles:[Codespace](https://docs.github.com/en/codespaces/overview):
+
    * From this project's main page, click **Code**, then **Codespace**.
-   * Choose **Create codespace on <branch_name>** to [create a codespace](https://docs.github.com/en/codespaces/developing-in-a-codespace/creating-a-codespace-for-a-repository#creating-a-codespace-for-a-repository) with the default resources (currently 2 CPU, 8 GB RAM, 32 GB Storage).
-   <img alt="create codespace button" title="create codespace button" src="https://docs.github.com/assets/cb-49943/mw-1440/images/help/codespaces/who-will-pay.webp" width="275px"/>
+   * Choose **Create codespace on &lt;branch_name&gt;**
+
+   This [creates a codespace](https://docs.github.com/en/codespaces/developing-in-a-codespace/creating-a-codespace-for-a-repository#creating-a-codespace-for-a-repository)
+   with the default resources (currently 2 CPU, 8 GB RAM, 32 GB Storage).
+
+   * :rocket: Run fnsort on your markdown file:
 
    ```bash
    /app/fnsort.py path/to/doc.md
    ```
 
 > [!IMPORTANT]
-> Keep in mind there are [monthly limits measured in core hours](https://docs.github.com/en/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces#monthly-included-storage-and-core-hours-for-personal-accounts) and to [stop your codespace](https://docs.github.com/en/codespaces/developing-in-a-codespace/stopping-and-starting-a-codespace):stop_sign: when you're not using it to conserve your monthly core hours allowance.
+> Keep in mind there are
+> [monthly limits measured in core hours](https://docs.github.com/en/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces#monthly-included-storage-and-core-hours-for-personal-accounts)
+and to
+[stop your codespace](https://docs.github.com/en/codespaces/developing-in-a-codespace/stopping-and-starting-a-codespace)
+:stop_sign: when you're not using it to conserve your monthly core hours
+allowance.
 
 ## Command Line Arguments
+
 ### --adjacent
-Adjacent inline references that are not separated by other characters become problematic (by default).
-This option adds spacing between those inline references so they are properly identified during sorting.
+
+Adjacent inline references that are not separated by other characters become
+problematic (by default).
+This option adds spacing between those inline references so they are properly
+identified during sorting.
 
 `fnsort.py path/to/doc.md --adjacent`
 
 ### --keepnames
+
 Retain or keep inline reference and footnote names.
 This prevents the default behavior of replacing the names with numbers.
 Footnotes at the end of the markdown are **still sorted**.
 
 `fnsort.py path/to/doc.md --keepnames`
 
 ## Contributing
-For information about contributing to this project, see the [contributing guidelines](CONTRIBUTING.md).
+
+For information about contributing to this project, see the
+[contributing guidelines](CONTRIBUTING.md).

fnsort.py

@@ -139,7 +139,8 @@ def sort_footnotes(text, args):
         # Rewrite the footnote-links with the new footnote-reference numbers.
         text = link.sub(lambda m: replace_reference(m, order), text)
 
-    return text
+    # Append newline to EOL to appease markdownlint
+    return f"{text}\n"
 
 
 def main():

tests/adjacent/adjacent.md

@@ -1,31 +1,46 @@
 # Wrens
 
 ## Overview
+
 Wrens [^4][^7] are a family of brown birds of which there are 88 species.
 
 ## Size
-Wrens are medium-small to very small birds. The Eurasian wren is among the smallest birds in its range, while the smaller species from the Americas are among the smallest passerines in that part of the world.[^1]
+
+Wrens are medium-small to very small birds. The Eurasian wren is among the
+smallest birds in its range, while the smaller species from the Americas are
+among the smallest passerines in that part of the world.[^1]
 
 ## Coloration
-The dominating colors of their plumage are generally drab, composed of gray, brown, black, and white, and most species show some barring, especially on the tail or wings[^1].
+
+The dominating colors of their plumage are generally drab, composed of gray,
+brown, black, and white, and most species show some barring, especially on the
+tail or wings[^1].
 
 ## Diet
-Wrens are primarily insectivorous, eating insects, spiders and other small invertebrates, but many species also eat vegetable matter and some eat small frogs and lizards[^4][^7].
+
+Wrens are primarily insectivorous, eating insects, spiders and other small
+invertebrates, but many species also eat vegetable matter and some eat small
+frogs and lizards[^4][^7].
 
 ## Species
+
 ### Eurasian Wren
-![Eurasian wren](https://upload.wikimedia.org/wikipedia/commons/thumb/6/6c/Ein_neugieriger_Zaunk%C3%B6nig.jpg/240px-Ein_neugieriger_Zaunk%C3%B6nig.jpg)[^3]
 
-The Eurasian wren is the only species of wren found outside the Americas, as restricted to Europe, Asia, and northern Africa.[^2]
+![Eurasian wren](https://upload.wikimedia.org/wikipedia/commons/thumb/6/6c/Ein_neugieriger_Zaunk%C3%B6nig.jpg/240px-Ein_neugieriger_Zaunk%C3%B6nig.jpg)
+Credit:[^3]
+
+The Eurasian wren is the only species of wren found outside the Americas, as
+restricted to Europe, Asia, and northern Africa.[^2]
 
-The Eurasian wren has been recorded wading into shallow water to catch small fish and tadpoles[^6] .
+The Eurasian wren has been recorded wading into shallow water to catch small
+fish and tadpoles[^6] .
 
 The most common call of the Eurasian is a sharp repeated "tic-tic-tic"[^5].
 
-[^4]: https://en.wikipedia.org/wiki/Wren
-[^7]: https://www.allaboutbirds.org/guide/browse/shape/Wrens
-[^1]: https://en.wikipedia.org/wiki/Wren#Description
-[^5]: https://en.wikipedia.org/wiki/Eurasian_wren#Vocalizations
-[^2]: https://en.wikipedia.org/wiki/Wren#Distribution_and_habitat
-[^6]: https://en.wikipedia.org/wiki/Wren#Behavior_and_ecology
-[^3]: https://en.wikipedia.org/wiki/File:Ein_neugieriger_Zaunk%C3%B6nig.jpg
+[^4]: <https://en.wikipedia.org/wiki/Wren>
+[^7]: <https://www.allaboutbirds.org/guide/browse/shape/Wrens>
+[^1]: <https://en.wikipedia.org/wiki/Wren#Description>
+[^5]: <https://en.wikipedia.org/wiki/Eurasian_wren#Vocalizations>
+[^2]: <https://en.wikipedia.org/wiki/Wren#Distribution_and_habitat>
+[^6]: <https://en.wikipedia.org/wiki/Wren#Behavior_and_ecology>
+[^3]: <https://en.wikipedia.org/wiki/File:Ein_neugieriger_Zaunk%C3%B6nig.jpg>

tests/adjacent/adjacent_expected.md

@@ -1,31 +1,46 @@
 # Wrens
 
 ## Overview
+
 Wrens [^1] [^2] are a family of brown birds of which there are 88 species.
 
 ## Size
-Wrens are medium-small to very small birds. The Eurasian wren is among the smallest birds in its range, while the smaller species from the Americas are among the smallest passerines in that part of the world. [^3]
+
+Wrens are medium-small to very small birds. The Eurasian wren is among the
+smallest birds in its range, while the smaller species from the Americas are
+among the smallest passerines in that part of the world. [^3]
 
 ## Coloration
-The dominating colors of their plumage are generally drab, composed of gray, brown, black, and white, and most species show some barring, especially on the tail or wings [^3].
+
+The dominating colors of their plumage are generally drab, composed of gray,
+brown, black, and white, and most species show some barring, especially on the
+tail or wings [^3].
 
 ## Diet
-Wrens are primarily insectivorous, eating insects, spiders and other small invertebrates, but many species also eat vegetable matter and some eat small frogs and lizards [^1] [^2].
+
+Wrens are primarily insectivorous, eating insects, spiders and other small
+invertebrates, but many species also eat vegetable matter and some eat small
+frogs and lizards [^1] [^2].
 
 ## Species
+
 ### Eurasian Wren
-![Eurasian wren](https://upload.wikimedia.org/wikipedia/commons/thumb/6/6c/Ein_neugieriger_Zaunk%C3%B6nig.jpg/240px-Ein_neugieriger_Zaunk%C3%B6nig.jpg) [^4]
 
-The Eurasian wren is the only species of wren found outside the Americas, as restricted to Europe, Asia, and northern Africa. [^5]
+![Eurasian wren](https://upload.wikimedia.org/wikipedia/commons/thumb/6/6c/Ein_neugieriger_Zaunk%C3%B6nig.jpg/240px-Ein_neugieriger_Zaunk%C3%B6nig.jpg)
+Credit: [^4]
+
+The Eurasian wren is the only species of wren found outside the Americas, as
+restricted to Europe, Asia, and northern Africa. [^5]
 
-The Eurasian wren has been recorded wading into shallow water to catch small fish and tadpoles [^6] .
+The Eurasian wren has been recorded wading into shallow water to catch small
+fish and tadpoles [^6] .
 
 The most common call of the Eurasian is a sharp repeated "tic-tic-tic" [^7].
 
-[^1]: https://en.wikipedia.org/wiki/Wren
-[^2]: https://www.allaboutbirds.org/guide/browse/shape/Wrens
-[^3]: https://en.wikipedia.org/wiki/Wren#Description
-[^4]: https://en.wikipedia.org/wiki/File:Ein_neugieriger_Zaunk%C3%B6nig.jpg
-[^5]: https://en.wikipedia.org/wiki/Wren#Distribution_and_habitat
-[^6]: https://en.wikipedia.org/wiki/Wren#Behavior_and_ecology
-[^7]: https://en.wikipedia.org/wiki/Eurasian_wren#Vocalizations
+[^1]: <https://en.wikipedia.org/wiki/Wren>
+[^2]: <https://www.allaboutbirds.org/guide/browse/shape/Wrens>
+[^3]: <https://en.wikipedia.org/wiki/Wren#Description>
+[^4]: <https://en.wikipedia.org/wiki/File:Ein_neugieriger_Zaunk%C3%B6nig.jpg>
+[^5]: <https://en.wikipedia.org/wiki/Wren#Distribution_and_habitat>
+[^6]: <https://en.wikipedia.org/wiki/Wren#Behavior_and_ecology>
+[^7]: <https://en.wikipedia.org/wiki/Eurasian_wren#Vocalizations>