Add a markdown linter and formatter for development (#1472)

nathanjmcdougall · web-flow · commit ba2fd0479f9b · 2026-03-23T14:35:10.000+13:00
diff --git a/.agents/skills/github-actions-update/SKILL.md b/.agents/skills/github-actions-update/SKILL.md
@@ -15,7 +15,7 @@ These are in `.github/workflows/`.
 
 Avoid redundant glob patterns. For in this example:
 
-```
+```yaml
 on:
   push:
     paths-ignore:
diff --git a/.agents/skills/usethis-qa-import-linter/SKILL.md b/.agents/skills/usethis-qa-import-linter/SKILL.md
@@ -21,7 +21,7 @@ uv run lint-imports
 
 ## Configuration File
 
-This project uses the `.importlinter` INI file to configure Import Linter. You specify _contracts_ which need to be complied with between modules' imports. For the `usethis` project, we mainly use the `layers` contract: earlier listed "higher" layers are not allowed to import from any "lower" layers. 
+This project uses the `.importlinter` INI file to configure Import Linter. You specify _contracts_ which need to be complied with between modules' imports. For the `usethis` project, we mainly use the `layers` contract: earlier listed "higher" layers are not allowed to import from any "lower" layers.
 
 ### Example Structure
 
diff --git a/.agents/skills/usethis-qa-static-checks/SKILL.md b/.agents/skills/usethis-qa-static-checks/SKILL.md
@@ -18,6 +18,6 @@ uv run basedpyright
 
 Note that we are interested in both errors and warnings from these tools - we should always fix both.
 
-## When to run these checks:
+## When to run these checks
 
 Before submitting changes for review, **always** run these static checks. This should be done every time, even for small changes, to avoid slowing down the code review process unnecessarily.
diff --git a/.github/ISSUE_TEMPLATE/bug-report.md b/.github/ISSUE_TEMPLATE/bug-report.md
@@ -1,10 +1,9 @@
 ---
 name: Bug Report
 about: Describe a bug or anything else that seems wrong
-title: ''
-labels: 'bug'
+title: ""
+labels: "bug"
 assignees: nathanjmcdougall
-
 ---
 
 **Background**
diff --git a/.github/ISSUE_TEMPLATE/enhancement.md b/.github/ISSUE_TEMPLATE/enhancement.md
@@ -1,10 +1,9 @@
 ---
 name: Enhancement Request
 about: A high-level description of a feature or other enhancement you'd like
-title: ''
-labels: ''
+title: ""
+labels: ""
 assignees: nathanjmcdougall
-
 ---
 
 **Motivation**
diff --git a/.markdownlint.yml b/.markdownlint.yml
@@ -0,0 +1,4 @@
+line-length:
+  line_length: 999 # Effectively soft-wrapping
+no-inline-html: false
+no-duplicate-heading: false
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -52,6 +52,18 @@ repos:
         priority: 0
       - id: ruff-format
         priority: 0
+  - repo: https://github.com/DavidAnson/markdownlint-cli2
+    rev: v0.22.0
+    hooks:
+      - id: markdownlint-cli2
+        args: ["--fix"]
+        priority: 0
+  - repo: https://github.com/rbubley/mirrors-prettier
+    rev: v3.8.1
+    hooks:
+      - id: prettier
+        types_or: [markdown]
+        priority: 0
   - repo: https://github.com/codespell-project/codespell
     rev: v2.4.1
     hooks:
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -497,7 +497,7 @@
 ### 🚀 New Features
 
 - The Ruff linter and formatter can now be configured independently. When using the `usethis tool ruff` command, you can now specify whether to add or remove the linter or formatter independently using the `--linter` and `--formatter` options. This allows for more granular control over which components of Ruff are used in your project. By default, as before, both the linter and formatter will be added or removed together.
-This introduces a change in the way that Bitbucket Pipelines steps will be configured for Ruff, by having the linter and formatter as separate steps.
+  This introduces a change in the way that Bitbucket Pipelines steps will be configured for Ruff, by having the linter and formatter as separate steps.
 
 - Integrations with Ruff for pre-commit and Bitbucket Pipelines will determine whether the linter or formatter is being used based on the presence of the `ruff.lint` and `ruff.format` keys the active Ruff configuration file.
 
@@ -541,7 +541,7 @@ This introduces a change in the way that Bitbucket Pipelines steps will be confi
 
 - The `--quiet` option did not properly suppress output when displaying warnings associated with failed README parsing in `usethis badge`. This has been fixed.
 
-- Due to a breaking change in Click v8.2.0, Click is now declared as a direct dependency temporarily until the ramifications can be addressed in Typer. The lower bound is declared as `>=8.0.0` and the constraint `!=8.2.0` to avoid the breaking change. For more information, see [here](https://github.com/fastapi/typer/discussions/1215).
+- Due to a breaking change in Click v8.2.0, Click is now declared as a direct dependency temporarily until the ramifications can be addressed in Typer. The lower bound is declared as `>=8.0.0` and the constraint `!=8.2.0` to avoid the breaking change. For more information, see [this discussion on the Typer GitHub repository](https://github.com/fastapi/typer/discussions/1215).
 
 ### 🧹 Maintenance
 
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -17,23 +17,23 @@ diverse, inclusive, and healthy community.
 Examples of behavior that contributes to a positive environment for our
 community include:
 
-* Demonstrating empathy and kindness toward other people
-* Being respectful of differing opinions, viewpoints, and experiences
-* Giving and gracefully accepting constructive feedback
-* Accepting responsibility and apologizing to those affected by our mistakes,
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
   and learning from the experience
-* Focusing on what is best not just for us as individuals, but for the
+- Focusing on what is best not just for us as individuals, but for the
   overall community
 
 Examples of unacceptable behavior include:
 
-* The use of sexualized language or imagery, and sexual attention or
+- The use of sexualized language or imagery, and sexual attention or
   advances of any kind
-* Trolling, insulting or derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or email
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email
   address, without their explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
+- Other conduct which could reasonably be considered inappropriate in a
   professional setting
 
 ## Enforcement Responsibilities
@@ -106,7 +106,7 @@ Violating these terms may lead to a permanent ban.
 ### 4. Permanent Ban
 
 **Community Impact**: Demonstrating a pattern of violation of community
-standards, including sustained inappropriate behavior,  harassment of an
+standards, including sustained inappropriate behavior, harassment of an
 individual, or aggression toward or disparagement of classes of individuals.
 
 **Consequence**: A permanent ban from any sort of public interaction within
@@ -116,13 +116,13 @@ the community.
 
 This Code of Conduct is adapted from the [Contributor Covenant][homepage],
 version 2.0, available at
-https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+<https://www.contributor-covenant.org/version/2/0/code_of_conduct.html>.
 
 Community Impact Guidelines were inspired by [Mozilla's code of conduct
 enforcement ladder](https://github.com/mozilla/diversity).
 
 [homepage]: https://www.contributor-covenant.org
 
 For answers to common questions about this code of conduct, see the FAQ at
-https://www.contributor-covenant.org/faq. Translations are available at
-https://www.contributor-covenant.org/translations.
+<https://www.contributor-covenant.org/faq>. Translations are available at
+<https://www.contributor-covenant.org/translations>.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -116,10 +116,10 @@ Along with the fonts [EB Garamond](https://fonts.google.com/specimen/EB+Garamond
 
 To add a new `usethis badge` interface, follow these steps:
 
-- Define a `get_<badge_name>_badge` function in <src\usethis\_core\badge.py>. Try to keep the definitions in alphabetical order.
-- Declare the interface in <src\usethis\_ui\interface\badge.py>. Again, keep the declarations in alphabetical order. The pattern is basically just boilerplate with the other interfaces, but you need to give a description of your command for the `--help` option.
-- Add a test for your badge in <tests\usethis\_ui\interface\test_interface_badge.py>. Follow the pattern of the existing tests, although you only need the `test_add` case, which simply tests that the command runs without error.
-- Declare a recommended badge placement in the `get_badge_order` function in <src\usethis\_core\badge.py>. This helps ensure the badges are arranged in an opinionated way relative to existing badges.
+- Define a `get_<badge_name>_badge` function in <src\usethis_core\badge.py>. Try to keep the definitions in alphabetical order.
+- Declare the interface in <src\usethis_ui\interface\badge.py>. Again, keep the declarations in alphabetical order. The pattern is basically just boilerplate with the other interfaces, but you need to give a description of your command for the `--help` option.
+- Add a test for your badge in <tests\usethis_ui\interface\test_interface_badge.py>. Follow the pattern of the existing tests, although you only need the `test_add` case, which simply tests that the command runs without error.
+- Declare a recommended badge placement in the `get_badge_order` function in <src\usethis_core\badge.py>. This helps ensure the badges are arranged in an opinionated way relative to existing badges.
 
 Finally, run the command on this project, to make sure the badge gets inserted correctly with valid Markdown syntax. Check it renders successfully and that any hyperlink works as expected.
 
diff --git a/README.md b/README.md
@@ -1,5 +1,5 @@
 <h1 align="center">
-  <img src="https://raw.githubusercontent.com/usethis-python/usethis-python/refs/heads/main/docs/logo.svg"><br>
+  <img src="https://raw.githubusercontent.com/usethis-python/usethis-python/refs/heads/main/docs/logo.svg" alt="usethis logo" ><br>
 </h1>
 
 # usethis
diff --git a/docs/cli/reference.md b/docs/cli/reference.md
@@ -26,12 +26,14 @@ Supported options:
 
   Possible values:
   - `bitbucket` for [Bitbucket Pipelines](https://bitbucket.org/product/features/pipelines)
+
 - `--docstyle` to set a docstring style convention for the project.
 
   Possible values:
   - `numpy` for [NumPy docstring style](https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard)
   - `google` for [Google docstring style](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings)
   - `pep257` for [PEP 257 docstring style](https://www.python.org/dev/peps/pep-0257/)
+
 - `--status` to set the development status of the project. Defaults to `planning`.
 
   Possible values:
@@ -42,6 +44,7 @@ Supported options:
   - `production` or `5` for "Development Status :: 5 - Production/Stable"
   - `mature` or `6` for "Development Status :: 6 - Mature"
   - `inactive` or `7` for "Development Status :: 7 - Inactive"
+
 - `--offline` to disable network access and rely on caches
 - `--quiet` to suppress output
 - `--frozen` to leave the virtual environment and lockfile unchanged (i.e. do not install dependencies, nor update lockfiles)
@@ -194,7 +197,7 @@ Supported options:
 - `--frozen` to leave the virtual environment and lockfile unchanged
 - `--quiet` to suppress output
 - `--backend` to specify a package manager backend to use. The default is to auto-detect.
-Possible values:
+  Possible values:
   - `auto` to auto-detect the backend (default)
   - `uv` to use the [uv](https://docs.astral.sh/uv) package manager
   - `none` to not use a package manager backend and display messages for some operations.
@@ -219,7 +222,7 @@ Supported options:
 - `--frozen` to leave the virtual environment and lockfile unchanged
 - `--quiet` to suppress output
 - `--backend` to specify a package manager backend to use. The default is to auto-detect.
-Possible values:
+  Possible values:
   - `auto` to auto-detect the backend (default)
   - `uv` to use the [uv](https://docs.astral.sh/uv) package manager
   - `none` to not use a package manager backend and display messages for some operations.
diff --git a/docs/pipeweld.md b/docs/pipeweld.md
@@ -29,7 +29,7 @@ The informal notation above indicates a pipeline of two parallel steps A and B i
 We can also consider more a more complicated pipeline in the below diagram:
 
 ```Text
-(A | B | (C + D)) + E + (F | G) 
+(A | B | (C + D)) + E + (F | G)
 ```
 
 Here, A and B are in parallel with the series of steps C and D; those steps are all in series with step E, and then finally also in series we have the parallel steps F and G.
diff --git a/docs/start/detailed-example.md b/docs/start/detailed-example.md
@@ -17,14 +17,14 @@ Let's run through what each line of the output means:
 1. `✔ Adding dependency 'ruff' to the 'dev' group in 'pyproject.toml'.`  
    This line indicates that the `ruff` package has been added as a development dependency in the `pyproject.toml` file. This means that `ruff` has been installed automatically via `uv`, but also that it is recorded in the project's dependency list for others when they start working on the project (e.g. with `uv sync`).
 2. `✔ Adding Ruff config to 'pyproject.toml'.`
-    This line indicates that a configuration section for Ruff has been added to the `pyproject.toml` file. This section contains settings that control how Ruff behaves when it is run. The settings adopted by usethis are "context aware" - based on the structure of your project, other tools you are using, etc., and so they are more likely to be appropriate for your project than the default settings.
+   This line indicates that a configuration section for Ruff has been added to the `pyproject.toml` file. This section contains settings that control how Ruff behaves when it is run. The settings adopted by usethis are "context aware" - based on the structure of your project, other tools you are using, etc., and so they are more likely to be appropriate for your project than the default settings.
 3. `✔ Selecting Ruff rules 'A', 'C4', 'E4', 'E7', 'E9', 'F', 'FLY', 'FURB', 'I', 'PLE', 'PLR', 'RUF', 'SIM', 'UP' in 'pyproject.toml'.`
-    This line indicates that a set of recommended Ruff rule sets has been selected and added to the `pyproject.toml` configuration. These rules determine what kinds of issues Ruff will check for in your code. The selected rules are based on best practices and are intended to help you maintain high code quality. Most of them have auto-fixes available. You can learn more about the specific rules in the [Ruff documentation](https://docs.astral.sh/ruff/rules).
+   This line indicates that a set of recommended Ruff rule sets has been selected and added to the `pyproject.toml` configuration. These rules determine what kinds of issues Ruff will check for in your code. The selected rules are based on best practices and are intended to help you maintain high code quality. Most of them have auto-fixes available. You can learn more about the specific rules in the [Ruff documentation](https://docs.astral.sh/ruff/rules).
 4. `✔ Ignoring Ruff rules 'PLR2004', 'SIM108' in 'pyproject.toml'.`  
-    This line indicates that certain Ruff rules have been explicitly ignored in the configuration. These rules were deemed less useful or potentially problematic for most projects, so usethis has chosen to disable them by default. You can always modify this list later if you find that you want to enable or disable additional rules.
+   This line indicates that certain Ruff rules have been explicitly ignored in the configuration. These rules were deemed less useful or potentially problematic for most projects, so usethis has chosen to disable them by default. You can always modify this list later if you find that you want to enable or disable additional rules.
 5. `☐ Run 'uv run ruff check --fix' to run the Ruff linter with autofixes.`  
-    This line is an instruction for you to run the Ruff linter on your codebase. It helps teach you how to use the tool which has just been installed and configured. You're ready to go and explore!
+   This line is an instruction for you to run the Ruff linter on your codebase. It helps teach you how to use the tool which has just been installed and configured. You're ready to go and explore!
 6. `☐ Run 'uv run ruff format' to run the Ruff formatter.`
-    Ruff is also a code formatter. Similar to the previous line, this is an instruction for you to run the Ruff formatter on your codebase. This will help ensure that your code adheres to consistent formatting standards.
+   Ruff is also a code formatter. Similar to the previous line, this is an instruction for you to run the Ruff formatter on your codebase. This will help ensure that your code adheres to consistent formatting standards.
 
 The key idea is that lines beginning with a check mark (✔) indicate actions that have been successfully completed by usethis, while lines beginning with an empty box (☐) are instructions for you to follow up on.
