diff --git a/docs/assets/images/studio_fix_link.webp b/docs/assets/images/studio_fix_link.webp new file mode 100644 index 0000000..81e50c1 Binary files /dev/null and b/docs/assets/images/studio_fix_link.webp differ diff --git a/docs/setup/validation.md b/docs/setup/validation.md index c3be18c..9f3c166 100644 --- a/docs/setup/validation.md +++ b/docs/setup/validation.md @@ -8,52 +8,64 @@ status: new # Validation -Broken links are easy to miss – pages get renamed or moved, and references silently stop working. Zensical validates all internal links at build time by scanning every Markdown file and resolving all references: inline links, reference-style links, footnotes, link definitions, and anchors. +Broken links are easy to miss – pages get renamed or moved, and references silently stop working. Zensical validates all internal links at build time by scanning every Markdown file and resolving both inline links and reference-style links. Checks include invalid link anchors. Additionally, the build can be aborted when issues are found by enabling [strict mode]. -??? warning "Temporary limitations" +
+!!! tip "Zensical Studio" - Validation is provided on a best-effort basis. Since Python Markdown does not provide an AST, link detection relies on the same regex-based approach that Python Markdown uses internally. This is a temporary limitation – our planned migration to CommonMark will provide a proper AST, making this trivial to resolve. + With [Zensical Studio], we are delivering in-editor support for link + checking and refactorings that update links when headings change or + when files are renamed or moved. Catch problems like broken links as + you author, instead of only in a build. - __Please keep in mind__: + ![alt](../assets/images/studio_fix_link.webp) + + Parsing in Zensical Studio is based on our own Python Markdown parser, + which enables a host of other improvements in the authoring experience, + especially navigation and refactorings. We will publish the parser as + Open Source in the coming months and integrate into Zensical as the new + basis for validation during builds. +
+ + [Zensical Studio]: https://zensical.org/studio/ - - Autorefs are currently reported as [unresolved references]. We're working on a solution. - - Don't use nested brackets in link text, e.g. `[some[nested]](href)` or `[some[nested]][id]`. [strict mode]: #strict-mode [unresolved references]: #unresolved_references ## Configuration -Validation is enabled by default. All checks can be individually toggled: +Link validation is enabled by default and you can turn on other checks. Note, +however, that these are deprecated in their current form. === "`zensical.toml`" ``` toml [project.validation] - unresolved_references = true - unresolved_footnotes = true - unused_definitions = true - unused_footnotes = true - shadowed_definitions = true - shadowed_footnotes = true invalid_links = true invalid_link_anchors = true + unresolved_references = false + unresolved_footnotes = false + unused_definitions = false + unused_footnotes = false + shadowed_definitions = false + shadowed_footnotes = false ``` === "`mkdocs.yml`" ``` yaml validation: - unresolved_references: true - unresolved_footnotes: true - unused_definitions: true - unused_footnotes: true - shadowed_definitions: true - shadowed_footnotes: true invalid_links: true invalid_link_anchors: true + unresolved_references: false + unresolved_footnotes: false + unused_definitions: false + unused_footnotes: false + shadowed_definitions: false + shadowed_footnotes: false ``` Validation can also be completely disabled: @@ -71,18 +83,97 @@ Validation can also be completely disabled: validation: false ``` -### Links and footnotes +### `invalid_links` + +Warn when a link points to a page that does not exist. + +=== "`zensical.toml`" + + ``` toml + [project.validation] + invalid_links = true + ``` + +=== "`mkdocs.yml`" + + ``` yaml + validation: + invalid_links: true + ``` + +__Example__ + +``` markdown title="index.md" +Oh no, [this page] does not exit. + +[this page]: non-existent.md +``` + +
+``` console +$ zensical build +... +Warning: page does not exist + ╭─[ index.md:3:14 ] + │ + 3 │ [this page]: non-existent.md + │ ───────┬─────── + │ ╰───────── page does not exist +───╯ +``` +
+ +--- + +### `invalid_link_anchors` + +Warn when a link points to an anchor that does not exist. + +=== "`zensical.toml`" + + ``` toml + [project.validation] + invalid_link_anchors = true + ``` + +=== "`mkdocs.yml`" + + ``` yaml + validation: + invalid_link_anchors: true + ``` + +__Example__ + +``` markdown title="index.md" +Oh no, [this section] does not exit. + +[this section]: page.md#non-existent +``` + +
+``` console +$ zensical build +... +Warning: anchor does not exist + ╭─[ index.md:3:31 ] + │ + 3 │ [this section]: page.md#non-existent + │ ──────┬───── + │ ╰─────── anchor does not exist +───╯ +``` +
-The following checks for links and footnotes are available: +### Deprecated checks -- [`unresolved_references`](#unresolved_references) -- [`unresolved_footnotes`](#unresolved_footnotes) -- [`unused_definitions`](#unused_definitions) -- [`unused_footnotes`](#unused_footnotes) -- [`shadowed_definitions`](#shadowed_definitions) -- [`shadowed_footnotes`](#shadowed_footnotes) -- [`invalid_links`](#invalid_links) -- [`invalid_link_anchors`](#invalid_link_anchors) +The following checks have been deprecated in their current form. While they do +work in most cases, they turned out to have too many edge cases that the +approach taken could not cover. You can still use them in your projects but be +aware that we will replace them with functionally equivalent ones once we +publish our Python Markdown parser and integrate it with Zensical. It already +powers [Zensical Studio](#studio), which we recommend you use to get direct +feedback and functionality to avoid links breaking in the first place. --- @@ -336,88 +427,6 @@ Warning: shadowed footnote definition --- -#### `invalid_links` - -Warn when a link points to a page that does not exist. - -=== "`zensical.toml`" - - ``` toml - [project.validation] - invalid_links = true - ``` - -=== "`mkdocs.yml`" - - ``` yaml - validation: - invalid_links: true - ``` - -__Example__ - -``` markdown title="index.md" -Oh no, [this page] does not exit. - -[this page]: non-existent.md -``` - -
-``` console -$ zensical build -... -Warning: page does not exist - ╭─[ index.md:3:14 ] - │ - 3 │ [this page]: non-existent.md - │ ───────┬─────── - │ ╰───────── page does not exist -───╯ -``` -
- ---- - -#### `invalid_link_anchors` - -Warn when a link points to an anchor that does not exist. - -=== "`zensical.toml`" - - ``` toml - [project.validation] - invalid_link_anchors = true - ``` - -=== "`mkdocs.yml`" - - ``` yaml - validation: - invalid_link_anchors: true - ``` - -__Example__ - -``` markdown title="index.md" -Oh no, [this section] does not exit. - -[this section]: page.md#non-existent -``` - -
-``` console -$ zensical build -... -Warning: anchor does not exist - ╭─[ index.md:3:31 ] - │ - 3 │ [this section]: page.md#non-existent - │ ──────┬───── - │ ╰─────── anchor does not exist -───╯ -``` -
- ## Usage Just you write your content as usual, and Zensical will automatically validate all links and footnotes at build time.