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

Configurable diagnostics around broken links to docs

Browse Source 
Expand the situations where logs about broken links are produced, make the logging levels fully configurable
This commit is contained in:
Oleh Prypin
2023-06-30 16:42:42 +02:00
parent c71bf2429f
commit 4150d2b8ce
8 changed files with 311 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -343,17 +343,85 @@ Example:
```yaml
nav:
- Foo: foo.md
- Bar: bar.md
- Foo: foo.md
- Bar: bar.md
not_in_nav: |
/private.md
/private.md
```
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:
> nav:
> absolute_links: ignore
> links:
> absolute_links: ignore
> unrecognized_links: ignore
> ```
<!-- -->
>! EXAMPLE: **Recommended settings for most sites (maximal strictness):**
>
> ```yaml
> validation:
> nav:
> omitted_files: warn
> absolute_links: warn
> links:
> absolute_links: warn
> unrecognized_links: warn
> ```
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