Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Conversation

@polarathene
Copy link
Member

@polarathene polarathene commented Feb 16, 2025

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 polarathene added this to the v15.0.0 milestone Feb 16, 2025
@polarathene polarathene self-assigned this Feb 16, 2025
@polarathene polarathene added the kind/bug/fix A fix (PR) for a confirmed bug label Feb 16, 2025
@github-actions
Copy link
Contributor

Documentation preview for this PR is ready! 🎉

Built with commit: 77b999b

@georglauterbach georglauterbach merged commit 07e558e into master Feb 16, 2025
3 checks passed
@georglauterbach georglauterbach deleted the docs/fix-broken-ref-links branch February 16, 2025 09:22
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.

3 participants