docs: Tidy up formatting as suggested by markdownlint

.github/CONTRIBUTING.md

@@ -1,3 +1,4 @@
 # Contributing
 
-See https://chezmoi.io/developer-guide/contributing-changes/.
+See the [contributing
+guide](https://chezmoi.io/developer-guide/contributing-changes/).

.github/SECURITY.md

@@ -1,3 +1,3 @@
 # Security
 
-See https://chezmoi.io/developer-guide/security/.
+See the [security guide](https://chezmoi.io/developer-guide/security/).

.github/workflows/main.yml

@@ -433,6 +433,9 @@ jobs:
       if: github.event_name == 'pull_request' && github.event.pull_request.draft == false
       run: |
         go run ./internal/cmds/lint-commit-messages ${{ github.event.pull_request.head.sha }}~${{ github.event.pull_request.commits }}..${{ github.event.pull_request.head.sha }}
+    - name: lint-markdown
+      if: false # FIXME
+      uses: DavidAnson/markdownlint-cli2-action@a23dae216ce3fee4db69da41fed90d2a4af801cf
   lint:
     name: lint-${{ matrix.runs-on }}
     strategy:

.markdownlint-cli2.yaml

@@ -0,0 +1,8 @@
+globs:
+- '**/*.md'
+ignores:
+- .github/ISSUE_TEMPLATE/*.md
+- .venv
+- assets/chezmoi.io/docs/reference/release-history.md
+config:
+  line-length: false

Makefile

@@ -124,6 +124,10 @@ lint: ensure-actionlint ensure-editorconfig-checker ensure-find-typos ensure-gol
 	./bin/find-typos chezmoi .
 	go run ./internal/cmds/lint-commit-messages ${UPSTREAM}/master..HEAD
 
+.PHONY: lint-markdown
+lint-markdown:
+	markdownlint-cli2 --config .markdownlint-cli2.yaml
+
 .PHONY: format
 format: ensure-gofumpt ensure-golines
 	find . -name \*.go | xargs ./bin/golines --base-formatter="./bin/gofumpt -extra" --max-len=128 --write-output

README.md

@@ -10,9 +10,7 @@ If you're contributing to chezmoi, then please read the [developer guide](https:
 
 ## Contributors
 
-<a href="https://github.com/twpayne/chezmoi/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=twpayne/chezmoi&max=1024" />
-</a>
+![Contributor avatars](https://contrib.rocks/image?repo=twpayne/chezmoi&max=1024)
 
 ## License
 

assets/chezmoi.io/docs/developer-guide/architecture.md

@@ -6,8 +6,8 @@ interested in contributing to chezmoi.
 You can generate Go documentation for chezmoi's source code with `go doc`, for
 example:
 
-```console
-$ go doc -all -u github.com/twpayne/chezmoi/v2/internal/chezmoi
+```sh
+go doc -all -u github.com/twpayne/chezmoi/v2/internal/chezmoi
 ```
 
 You can also [browse chezmoi's generated documentation
@@ -22,7 +22,7 @@ The important directories in chezmoi are:
 | `assets/chezmoi.io/docs/`        | The documentation single source of truth. Help text, examples, and the [chezmoi.io](https://chezmoi.io) website are generated from the files in this directory |
 | `internal/chezmoi/`              | chezmoi's core functionality                                                                                                                                   |
 | `internal/cmd/`                  | Code for the `chezmoi` command                                                                                                                                 |
-| `internal/cmd/testdata/scripts/` | High-level tests of chezmoi's commands using [`testscript`](https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript)
+| `internal/cmd/testdata/scripts/` | High-level tests of chezmoi's commands using [`testscript`](https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript)                                     |
 
 ## Key concepts
 
@@ -169,8 +169,8 @@ with the test scripts themselves in
 
 You can run individual end-to-end tests with
 
-```console
-$ go test ./internal/cmd -run=TestScript/$TEST_NAME
+```sh
+go test ./internal/cmd -run=TestScript/$TEST_NAME
 ```
 
 Tests should, if at all possible, run unmodified on all operating systems

assets/chezmoi.io/docs/developer-guide/index.md

@@ -14,21 +14,21 @@ Go tooling. chezmoi requires Go 1.23 or later.
 
 Checkout chezmoi:
 
-```console
-$ git clone https://github.com/twpayne/chezmoi.git
-$ cd chezmoi
+```sh
+git clone https://github.com/twpayne/chezmoi.git
+cd chezmoi
 ```
 
 Build chezmoi:
 
-```console
-$ go build
+```sh
+go build
 ```
 
 Run all tests:
 
-```console
-$ go test ./...
+```sh
+go test ./...
 ```
 
 chezmoi's tests include integration tests with other software. If the other
@@ -39,28 +39,28 @@ of tests requires `age`, `base64`, `bash`, `bzip2`, `git`, `gpg`, `gzip`,
 
 Run chezmoi:
 
-```console
-$ go run .
+```sh
+go run .
 ```
 
 Run a set of smoke tests, including cross-compilation, tests, and linting:
 
-```console
-$ make smoke-test
+```sh
+make smoke-test
 ```
 
 Test building chezmoi for all architectures:
 
-```console
-$ make test-release
+```sh
+make test-release
 ```
 
 !!! hint
 
     If you use `fish` as your primary shell, you may get warnings from Fish
     during tests:
 
-    ```
+    ```text
     error: can not save history
     warning-path: Unable to locate data directory derived from $HOME: '/home/user/.local/share/fish'.
     warning-path: The error was 'Operation not supported'.
@@ -69,8 +69,8 @@ $ make test-release
 
     These can be avoided with by running tests with `SHELL=bash` or `SHELL=zsh`:
 
-    ```console
-    $ SHELL=bash make test
-    $ SHELL=zsh make smoke-test
-    $ SHELL=bash go test ./...
+    ```sh
+    SHELL=bash make test
+    SHELL=zsh make smoke-test
+    SHELL=bash go test ./...
     ```

assets/chezmoi.io/docs/developer-guide/install-script.md

@@ -4,8 +4,8 @@ chezmoi generates the [install
 script](https://github.com/twpayne/chezmoi/blob/master/assets/scripts/install.sh)
 from a single source of truth. You must run
 
-```console
-$ go generate
+```sh
+go generate
 ```
 
 if your change includes any of the following:

assets/chezmoi.io/docs/developer-guide/packaging.md

@@ -11,7 +11,7 @@ Please set the version number, git commit, and build time in the binary. This
 greatly assists debugging when end users report problems or ask for help. You
 can do this by passing the following flags to `go build`:
 
-```
+```text
 -ldflags "-X main.version=$VERSION
           -X main.commit=$COMMIT
           -X main.date=$DATE

assets/chezmoi.io/docs/developer-guide/releases.md

@@ -7,23 +7,23 @@ Releases are managed with [`goreleaser`](https://goreleaser.com/).
 To build a test release, without publishing, (Ubuntu Linux only) first ensure
 that the `musl-tools` and `snapcraft` packages are installed:
 
-```console
-$ sudo apt-get install musl-tools snapcraft
+```sh
+sudo apt-get install musl-tools snapcraft
 ```
 
 Then run:
 
-```console
-$ make test-release
+```sh
+make test-release
 ```
 
 ## Publishing
 
 Publish a new release by creating and pushing a tag, for example:
 
-```console
-$ git tag v1.2.3
-$ git push --tags
+```sh
+git tag v1.2.3
+git push --tags
 ```
 
 This triggers a [GitHub Action](https://github.com/twpayne/chezmoi/actions)
@@ -40,8 +40,8 @@ Release](https://github.com/twpayne/chezmoi/releases), and deploys the
     Snapcraft store credentials periodically expire. Create new snapcraft store
     credentials by running:
 
-    ```console
-    $ snapcraft export-login --snaps=chezmoi --channels=stable,candidate,beta,edge --acls=package_upload -
+    ```sh
+    snapcraft export-login --snaps=chezmoi --channels=stable,candidate,beta,edge --acls=package_upload -
     ```
 
 !!! note
@@ -53,8 +53,8 @@ Release](https://github.com/twpayne/chezmoi/releases), and deploys the
 
     If needed, the pull request can be created with:
 
-    ```console
-    $ brew bump-formula-pr --tag=v1.2.3 chezmoi
+    ```sh
+    brew bump-formula-pr --tag=v1.2.3 chezmoi
     ```
 
 !!! note

assets/chezmoi.io/docs/developer-guide/website.md

@@ -15,20 +15,20 @@ must be installed. Python 3.10 (or later) is required, but may be installed with
 
     If Python 3.10 (or later) is not currently installed, install it with `uv`:
 
-    ```console
-    $ uv python install 3.10
+    ```sh
+    uv python install 3.10
     ```
 
 Install the dependencies (the `--frozen` is optional but recommended):
 
-```console
-$ uv sync --frozen
+```sh
+uv sync --frozen
 ```
 
 Test the website locally by running:
 
-```console
-$ uv run task serve-docs
+```sh
+uv run task serve-docs
 ```
 
 and visiting [http://127.0.0.1:8000/](http://127.0.0.1:8000/).
@@ -38,6 +38,6 @@ and visiting [http://127.0.0.1:8000/](http://127.0.0.1:8000/).
 The website is automatically deployed when new releases are created, but manual
 deployments can be triggered by maintainers with appropriate access using:
 
-```console
-$ uv run task mkdocs gh-deploy
+```sh
+uv run task mkdocs gh-deploy
 ```

assets/chezmoi.io/docs/index.md.tmpl

@@ -25,17 +25,17 @@ With chezmoi, pronounced /ʃeɪ mwa/ (shay-mwa), you can install chezmoi and you
 dotfiles from your GitHub dotfiles repo on a new, empty machine with a single
 command:
 
-```console
-$ sh -c "$(curl -fsLS get.chezmoi.io)" -- init --apply $GITHUB_USERNAME
+```sh
+sh -c "$(curl -fsLS get.chezmoi.io)" -- init --apply $GITHUB_USERNAME
 ```
 
 As well as the `curl | sh` installation, you can [install chezmoi with your
 favorite package manager](install.md).
 
 Updating your dotfiles on any machine is a single command:
 
-```console
-$ chezmoi update
+```sh
+chezmoi update
 ```
 
 chezmoi runs on all popular operating systems, is distributed as a single