FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

docs: Fix broken ref links by polarathene · Pull Request #4366 · docker-mailserver/docker-mailserver · GitHub

docs: Fix broken ref links - #4366

Merged
georglauterbach merged 4 commits into
masterfrom
docs/fix-broken-ref-links
Feb 16, 2025
Merged

docs: Fix broken ref links#4366
georglauterbach merged 4 commits into
masterfrom
docs/fix-broken-ref-links

Conversation

polarathene commented Feb 16, 2025
edited
Loading

Copy link
Copy Markdown
Member

Description

Spotted a bad ref link (specifically the MD052 rule, we use "full" ref links), used a linter to search for any others and fixed those too.

# For `jq` to correctly output to new lines from the container stdout, you need `-t` (without `-i`)
# Otherwise output is staggered/indented: https://github.com/jqlang/jq/issues/1414
$ docker run --rm -t -v ./docs:/docs:Z,ro ghcr.io/igorshubovych/markdownlint-cli:latest \
  --disable default --enable MD052 --json '/docs/**/*.md' \
  | jq -r '.[] | "\(.fileName):\(.lineNumber) => \(.errorContext)"'

content/config/best-practices/dkim_dmarc_spf.md:57 => [email account setup][docs-accounts-add]
content/config/debugging.md:114 => [port forwarding driver][docs-rootless-portdriver]

Using linters on markdown aren't entirely reliable for our docs due to non-standard mkdocs syntax, notably admonitions not being recognized (thus indented content is treated as code blocks which causes false-positives such as with MD053 for detecting unused ref links).


Additionally added a note about false-positives when we have anchor links directly referencing admonitions content tabs:

$ docker run --rm -it -v ./docs:/docs:Z -w /docs squidfunk/mkdocs-material

INFO    -  Doc file 'config/advanced/kubernetes.md' contains a link '#deployment', but there is no such anchor on this page.
INFO    -  Doc file 'examples/tutorials/mailserver-behind-proxy.md' contains a link '../../config/advanced/kubernetes.md#using-the-proxy-protocol', but the doc 'config/advanced/kubernetes.md' does not contain an anchor '#using-the-proxy-protocol'.

The non-standard syntax doesn't allow us to add anchors (normally this can be done via mkdocs feature { #anchor-name }), and I think part of this false-positive is due to support implemented in mkdocs-material via an mkdocs extension.

polarathene added this to the v15.0.0 milestone Feb 16, 2025
polarathene self-assigned this Feb 16, 2025
polarathene added the kind/bug/fix A fix (PR) for a confirmed bug label Feb 16, 2025

Copy link
Copy Markdown
Contributor

Documentation preview for this PR is ready! 🎉

Built with commit: 77b999b

georglauterbach merged commit 07e558e into master Feb 16, 2025
georglauterbach deleted the docs/fix-broken-ref-links branch February 16, 2025 09:22
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/documentation kind/bug/fix A fix (PR) for a confirmed bug

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants


Back | FazBrowse Home | New Git URL