centersl/mkdocs
1
0
Fork 0
mirror of https://github.com/mkdocs/mkdocs.git synced 2026-03-27 09:58:31 +07:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #3283 from mkdocs/warnc

Browse Source 
Expand link validation, add configs for it
This commit is contained in:
Oleh Prypin
2023-07-09 16:04:37 +02:00
committed by GitHub
parent 8353493606 ba6d23e721
commit 89c7aa69ac
12 changed files with 941 additions and 342 deletions
Download Patch File Download Diff File Expand all files Collapse all files

64
docs/user-guide/configuration.md
View File

@@ -354,6 +354,70 @@ As the previous option, this follows the .gitignore pattern format.
NOTE: Adding a given file to [`exclude_docs`](#exclude_docs) takes precedence over and implies `not_in_nav`.
### validation
NEW: **New in version 1.5.**
Configure the strictness of MkDocs' diagnostic messages when validating links to documents.
This is a tree of configs, and for each one the value can be one of the three: `warn`, `info`, `ignore`. Which cause a logging message of the corresponding severity to be produced. The `warn` level is, of course, intended for use with `mkdocs build --strict` (where it becomes an error), which you can employ in continuous testing.
> EXAMPLE: **Defaults of this config as of MkDocs 1.5:**
>
> ```yaml
> validation:
> nav:
> omitted_files: info
> not_found: warn
> absolute_links: info
> links:
> not_found: warn
> absolute_links: info
> unrecognized_links: info
> ```
>
> (Note: you shouldn't copy this whole example, because it only duplicates the defaults. Only individual items that differ should be set.)
The defaults of some of the behaviors already differ from MkDocs 1.4 and below - they were ignored before.
>? EXAMPLE: **Configure MkDocs 1.5 to behave like MkDocs 1.4 and below (reduce strictness):**
>
> ```yaml
> validation:
> absolute_links: ignore
> unrecognized_links: ignore
> ```
<!-- -->
>! EXAMPLE: **Recommended settings for most sites (maximal strictness):**
>
> ```yaml
> validation:
> omitted_files: warn
> absolute_links: warn
> unrecognized_links: warn
> ```
Note how in the above examples we omitted the 'nav' and 'links' keys. Here `absolute_links:` means setting both `nav: absolute_links:` and `links: absolute_links:`.
Full list of values and examples of log messages that they can hide or make more prominent:
* `validation.nav.omitted_files`
* "The following pages exist in the docs directory, but are not included in the "nav" configuration: ..."
* `validation.nav.not_found`
* "A relative path to 'foo/bar.md' is included in the 'nav' configuration, which is not found in the documentation files."
* "A reference to 'foo/bar.md' is included in the 'nav' configuration, but this file is excluded from the built site."
* `validation.nav.absolute_links`
* "An absolute path to '/foo/bar.html' is included in the 'nav' configuration, which presumably points to an external resource."
<!-- -->
* `validation.links.not_found`
* "Doc file 'example.md' contains a relative link '../foo/bar.md', but the target is not found among documentation files."
* "Doc file 'example.md' contains a link to 'foo/bar.md' which is excluded from the built site."
* `validation.links.absolute_links`
* "Doc file 'example.md' contains an absolute link '/foo/bar.html', it was left as is. Did you mean 'foo/bar.md'?"
* `validation.links.unrecognized_links`
* "Doc file 'example.md' contains an unrecognized relative link '../foo/bar/', it was left as is. Did you mean 'foo/bar.md'?"
* "Doc file 'example.md' contains an unrecognized relative link 'mail\@example.com', it was left as is. Did you mean 'mailto:mail\@example.com'?"
## Build directories
### theme