ci: enforce consistent markdown formatting with rumdl

.github/workflows/ci.yaml

@@ -88,3 +88,9 @@ jobs:
       with:
         shfmt-version: 3.13.1
     - run: shfmt --diff .
+
+  rumdl-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: rvben/rumdl@v0.1.68

.pre-commit-config.yaml

@@ -20,3 +20,7 @@ repos:
         (curl -fsSL https://wfxr.mit-license.org/2017/license.txt && echo) > ./LICENSE &&
             git add ./LICENSE || { git checkout ./LICENSE && exit 1; }
       '
+- repo: https://github.com/rvben/rumdl-pre-commit
+  rev: v0.1.68
+  hooks:
+    - id: rumdl-fmt  # Auto-format and fail if issues remain

.rumdl.toml

@@ -0,0 +1,26 @@
+# rumdl configuration file
+
+# Global configuration options
+[global]
+
+# List of file/directory patterns to exclude from linting
+exclude = [
+    # Common directories to exclude
+    ".git",
+    ".github",
+]
+
+# Respect .gitignore files when scanning directories
+respect-gitignore = true
+
+# Disable rules
+# MD033: inline HTML
+disable = [ "MD033" ]
+
+# Rule-specific configurations
+
+[MD003]
+style = "setext"  # Heading style (atx, atx_closed, setext)
+
+[MD013]
+line-length = 120  # Maximum characters per line

AGENTS.md

@@ -1,6 +1,8 @@
-# Repository Guidelines
+Repository Guidelines
+=====================
 
-## Project Structure & Module Organization
+Project Structure & Module Organization
+---------------------------------------
 
 `forgit` is a shell-based Git helper, so most changes land in a small set of files:
 
@@ -13,7 +15,8 @@
 
 When you add or rename a command, update the implementation, shell wrappers, completions, tests, and docs together.
 
-## Build, Test, and Development Commands
+Build, Test, and Development Commands
+-------------------------------------
 
 There is no build step; validation is command-driven.
 
@@ -22,19 +25,33 @@ There is no build step; validation is command-driven.
 - `bash forgit.plugin.sh`: verify Bash compatibility.
 - `zsh forgit.plugin.zsh`: verify Zsh compatibility.
 - `fish conf.d/forgit.plugin.fish`: verify Fish compatibility.
+- `rumdl check .`
 
 CI runs these checks on macOS and Ubuntu. Keep local validation aligned with that workflow before opening a PR.
 
-## Coding Style & Naming Conventions
+Coding Style & Naming Conventions
+---------------------------------
 
-Follow `.editorconfig`: UTF-8, LF endings, spaces for indentation, width 4, and no trailing whitespace. Match the existing shell style: prefer small helper functions, `local` variables inside functions, and descriptive private names such as `_forgit_extract_branch_name`. Keep command aliases and completion names consistent across shells.
+Follow `.editorconfig`: UTF-8, LF endings, spaces for indentation, width 4, and no trailing whitespace.
+Match the existing shell style: prefer small helper functions, `local` variables inside functions,
+and descriptive private names such as `_forgit_extract_branch_name`.
+Keep command aliases and completion names consistent across shells.
 
-## Testing Guidelines
+Testing Guidelines
+------------------
 
-Tests use Bashunit and live in `tests/*.test.sh`. Name new files after the behavior under test, such as `worktree.test.sh` or `checkout.test.sh`. Source `bin/git-forgit` in tests and exercise helpers directly when possible. Add or update tests for behavior changes, especially parsing, selection, and cross-shell integration.
+Tests use Bashunit and live in `tests/*.test.sh`.
+Name new files after the behavior under test, such as `worktree.test.sh` or `checkout.test.sh`.
+Source `bin/git-forgit` in tests and exercise helpers directly when possible.
+Add or update tests for behavior changes, especially parsing, selection, and cross-shell integration.
 
-## Commit & Pull Request Guidelines
+Commit & Pull Request Guidelines
+--------------------------------
 
-Git history follows Conventional Commits: `feat: ...`, `fix: ...`, `docs: ...`, `refactor: ...`, and occasional scoped forms like `style(docs): ...`. Write messages around the behavior change and its reason, not just the implementation detail.
+Git history follows Conventional Commits: `feat: ...`, `fix: ...`, `docs: ...`, `refactor: ...`,
+and occasional scoped forms like `style(docs): ...`.
+Write messages around the behavior change and its reason, not just the implementation detail.
 
-Use the PR template. Before submitting, perform a self-review, update docs for user-visible changes, add tests when behavior changes, and report the shells and operating systems you verified.
+Use the PR template.
+Before submitting, perform a self-review, update docs for user-visible changes, add tests when behavior changes,
+and report the shells and operating systems you verified.

CONTRIBUTING.md

@@ -1,18 +1,22 @@
-# Contributing to forgit
+Contributing to forgit
+======================
 
 Thanks for your interest in contributing to `forgit`.
 
-This document covers the repository-specific workflow for reporting issues and opening pull requests. For installation, usage, commands, and configuration, see [README.md](README.md).
+This document covers the repository-specific workflow for reporting issues and opening pull requests.
+For installation, usage, commands, and configuration, see [README.md](README.md).
 
-## Before You Start
+Before You Start
+----------------
 
 Before opening an issue or pull request, please make sure that you:
 
 - read through [README.md](README.md)
 - use the latest released version of `forgit`
 - search existing issues and pull requests for duplicates
 
-## Repository Map
+Repository Map
+--------------
 
 These are the main places you will usually need to touch:
 
@@ -22,7 +26,8 @@ These are the main places you will usually need to touch:
 - [`completions/`](completions): tab completions for zsh, bash, and fish
 - [`tests/`](tests): [bashunit](https://bashunit.typeddevs.com/) test suite
 
-## Making Changes
+Making Changes
+--------------
 
 When changing or adding behavior, prefer to follow existing command patterns already used in the repository.
 
@@ -37,22 +42,25 @@ Please keep changes focused. Small pull requests are easier to review and usuall
 
 When possible, keep core logic testable by sourcing `bin/git-forgit` directly and calling helper functions from unit tests.
 
-## Development Dependencies
+Development Dependencies
+------------------------
 
 To run the same checks as CI, make sure these tools are available locally:
 
 - `bash`, `zsh`, and `fish`
 - `shellcheck`
 - `curl`
 - `bashunit` as `lib/bashunit`
+- `rumdl`
 
 If `lib/bashunit` is not available yet, install it once with:
 
 ```sh
 curl -s https://bashunit.typeddevs.com/install.sh | bash -s 0.31.0
 ```
 
-## Local Validation
+Local Validation
+----------------
 
 Before opening a pull request, run the checks that match the current CI workflow:
 
@@ -63,11 +71,13 @@ bash forgit.plugin.sh
 zsh forgit.plugin.zsh
 fish conf.d/forgit.plugin.fish
 shfmt --write .
+rumdl check .
 ```
 
 In your pull request, report which shells and operating systems you tested.
 
-## Commit Messages
+Commit Messages
+---------------
 
 This repository uses [Conventional Commits](https://www.conventionalcommits.org), and pull requests are checked accordingly in CI.
 
@@ -109,7 +119,8 @@ Document the repository-specific review, testing, and completion update
 expectations so new contributors do not have to infer them from old issues.
 ```
 
-## Pull Requests
+Pull Requests
+-------------
 
 Before submitting a pull request, make sure that you:
 
@@ -119,9 +130,11 @@ Before submitting a pull request, make sure that you:
 - update documentation when the change is user-visible
 - summarize the pull request in terms of what changed and why
 
-Please use the pull request description to give reviewers the context they need. A short explanation of the approach is useful, but the main focus should be the behavior change and its motivation.
+Please use the pull request description to give reviewers the context they need.
+A short explanation of the approach is useful, but the main focus should be the behavior change and its motivation.
 
-## Maintainers
+Maintainers
+-----------
 
 - [@wfxr](https://github.com/wfxr)
 - [@cjappl](https://github.com/cjappl)

README.md

@@ -122,11 +122,13 @@ apply = ["source"]
 ### Homebrew
 
 To install using brew
+
 ```sh
 brew install forgit
 ```
 
 Then add the following to your shell's config file:
+
 ```sh
 # Fish:
 # ~/.config/fish/config.fish:
@@ -143,11 +145,16 @@ Then add the following to your shell's config file:
 
 ### Arch User Repository
 
-[AUR](https://wiki.archlinux.org/title/Arch_User_Repository) packages, maintained by the developers of forgit, are available. Install the [forgit](https://aur.archlinux.org/packages/forgit) package for the latest release or [forgit-git](https://aur.archlinux.org/packages/forgit-git) to stay up to date with the latest commits from the default branch of this repository.
+[AUR](https://wiki.archlinux.org/title/Arch_User_Repository) packages, maintained by the developers of forgit,
+are available. Install the [forgit](https://aur.archlinux.org/packages/forgit) package for the latest release or
+[forgit-git](https://aur.archlinux.org/packages/forgit-git) to stay up to date with the latest commits from the default
+branch of this repository.
 
 ### Completions
 
-Forgit offers completions for all supported shells. Completions are automatically configured when installing forgit through Homebrew or the AUR. All other installation methods mentioned above require manual setup for completions. The necessary steps depend on the shell you use.
+Forgit offers completions for all supported shells. Completions are automatically configured when installing forgit
+through Homebrew or the AUR. All other installation methods mentioned above require manual setup for completions.
+The necessary steps depend on the shell you use.
 
 #### Bash
 
@@ -158,13 +165,18 @@ Forgit offers completions for all supported shells. Completions are automaticall
 
 #### Fish
 
-- Put [`completions/git-forgit.fish`](https://github.com/wfxr/forgit/blob/main/completions/git-forgit.fish) in `~/.config/fish/completions/` to have fish tab completion for `git forgit` and configured git aliases, as well as shell command aliases, such as `ga`.
+- Put [`completions/git-forgit.fish`](https://github.com/wfxr/forgit/blob/main/completions/git-forgit.fish) in
+`~/.config/fish/completions/` to have fish tab completion for `git forgit` and configured git aliases, as well as shell
+command aliases, such as `ga`.
 
 #### Zsh
 
-- Put [`completions/_git-forgit`](completions/_git-forgit) in a directory in your `$fpath` (e.g., `/usr/share/zsh/site-functions`) to have zsh tab completion for `git forgit` and configured git aliases, as well as shell command aliases, such as `forgit::add` and `ga`.
+- Put [`completions/_git-forgit`](completions/_git-forgit) in a directory in your `$fpath`
+(e.g., `/usr/share/zsh/site-functions`) to have zsh tab completion for `git forgit` and configured git aliases, as well
+as shell command aliases, such as `forgit::add` and `ga`.
 
-If you're having issues after updating, and commands such as `forgit::add` or aliases `ga` aren't working, remove your completions cache and restart your shell.
+If you're having issues after updating, and commands such as `forgit::add` or aliases `ga` aren't working, remove your
+completions cache and restart your shell.
 
 ```zsh
 > rm ~/.zcompdump
@@ -219,7 +231,7 @@ You can use forgit as a sub-command of git by making `git-forgit` available in `
 PATH="$PATH:$FORGIT_INSTALL_DIR/bin"
 ```
 
-*Some plugin managers can help do this.*
+_Some plugin managers can help do this._
 
 Then, any forgit command will be a sub-command of git:
 
@@ -304,7 +316,9 @@ variables:
 | `FORGIT_ATTRIBUTES_PAGER` | `bat -l gitattributes --color always` _or_ `cat` |
 | `FORGIT_PREVIEW_PAGER`    | Normal pager resolution<sup>*</sup>              |
 
-<sup>*</sup> If your pager is a TUI program (e.g., `diffnav`, `tig`), fzf preview panes will be blank because they run without a TTY. Set `FORGIT_PREVIEW_PAGER` to a non-interactive pager (e.g., `delta`) to fix this. When set, it overrides all other `FORGIT_*_PAGER` settings in fzf preview context.
+<sup>*</sup> If your pager is a TUI program (e.g., `diffnav`, `tig`), fzf preview panes will be blank because they run
+without a TTY. Set `FORGIT_PREVIEW_PAGER` to a non-interactive pager (e.g., `delta`) to fix this. When set, it
+overrides all other `FORGIT_*_PAGER` settings in fzf preview context.
 
 ### FZF Options