Skip to content

Implement validation of anchors in links to other pages#3463

Merged
oprypin merged 5 commits into
masterfrom
anch
Dec 9, 2023
Merged

Implement validation of anchors in links to other pages#3463
oprypin merged 5 commits into
masterfrom
anch

Conversation

@oprypin

@oprypin oprypin commented Nov 11, 2023

Copy link
Copy Markdown

Example message:

WARNING -  Doc file 'dev-guide/themes.md' contains a link '../user-guide/configuration.md#google_analytics', but the doc 'user-guide/configuration.md' does not contain an anchor '#google>

It is not enabled by default. To increase to warning level, use config validation: {anchors: warn}

The implementation only detects Markdown anchors, not raw HTML anchors. As such it may have false positives.

The implementation now detects both Markdown anchors and raw HTML anchors

<a id="undetectable-anchor"></a>

## Detectable anchor

But that's just about user-authored HTML.
As for HTML that Markdown extensions insert: it will also work correctly if they insert the HTML as etree elements and will never work if they insert it via htmlStash. Basically the same rules as for what toc_tokens is able to detect.


Extra commits:

  • Make File hashable, without __eq__
  • Docs: fix or drop broken anchor links
  • Set logging levels on the logger rather than just the stream
  • Update docs about logging in plugins

Oleh Prypin added 5 commits November 11, 2023 14:28
Otherwise currently `log.getEffectiveLevel()` always reports `1` and doesn't allow optimizing away debug logging statemets.
Example message:

    WARNING -  Doc file 'dev-guide/themes.md' contains a link '../user-guide/configuration.md#google_analytics', but the doc 'user-guide/configuration.md' does not contain an anchor '#google>

It is not enabled by default. To enable, use config `validation: {anchors: warn}`

The implementation only detects Markdown anchors, not raw HTML anchors. As such it may have false positives.

```markdown
<a id="undetectable-anchor"></a>

## Detectable anchor
```

There are plans to improve that in the future.

But that's just about user-authored HTML.
As for HTML that Markdown extensions insert: it will also work correctly if they insert the HTML as etree elements and will never work if they insert it via `htmlStash`. Basically the same rules as for what `toc_tokens` is able to detect.
Comment thread mkdocs/structure/pages.py

@pawamoy pawamoy left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice 👍

@ultrabug ultrabug left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍

@samuelcolvin

Copy link
Copy Markdown
Contributor

This is great, thank you!

@oprypin

This comment was marked as abuse.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Validate links to anchors on Markdown documents

4 participants