diff options
| author | Jim Newsome <jnewsome@torproject.org> | 2023-11-09 10:39:46 -0600 |
|---|---|---|
| committer | Jim Newsome <jnewsome@torproject.org> | 2023-11-09 18:45:20 -0600 |
| commit | 1eef207b51ddbb92c2bc4a02ae7b46929583355b (patch) | |
| tree | 4000a7da4865f654687a1e9acde19c6b4eaefbfe /mdbook | |
| parent | 9205c7a86ffbea46d16f0a13e205100fc3ba1c76 (diff) | |
| download | torspec-1eef207b51ddbb92c2bc4a02ae7b46929583355b.tar.gz torspec-1eef207b51ddbb92c2bc4a02ae7b46929583355b.zip | |
Use mdbook-linkcheck to detect missing defs for ref-style links
Suppose in raw markdown we have:
```markdown
See [foo][barr].
[bar]: https://link-to-bar
```
The intent is to link the text "foo", but because of a typo it used the
label barr instead of bar. The result is that the rendered html won't
have a link at all. The text will be rendered literally as
`[foo][barr]`. Since there's no link (not even a broken one), a link
checker run over the rendered output won't spot the problem.
The mdbook-linkcheck plugin correctly detects this issue. However, it
doesn't understand links that go between our two mdbook projects since
the relative paths in the source don't match the relative paths in the
rendered output. Since checking whether the links are non-broken is
already covered by `bin/check_links` (using linklint), we can disable
checking the link destinations altogether.
Diffstat (limited to 'mdbook')
| -rw-r--r-- | mdbook/proposals/book.toml | 10 | ||||
| -rw-r--r-- | mdbook/spec/book.toml | 10 |
2 files changed, 20 insertions, 0 deletions
diff --git a/mdbook/proposals/book.toml b/mdbook/proposals/book.toml index fdbe64a..8a6045b 100644 --- a/mdbook/proposals/book.toml +++ b/mdbook/proposals/book.toml @@ -19,6 +19,16 @@ theme = "../theme" # additional-js = ["theme/pagetoc.js"] no-section-label = true +[output.linkcheck] +warning-policy = "error" +# We effectively disable checking link destinations by excluding +# all links (`.*`). +# +# We're only using linkcheck to validate that reference-style links have *some* +# definition in the markdown, ensuring that *some* link will be generated. We +# validate that those links are correct using a separate tool (`bin/check_links`) +exclude = [ '.*' ] + [output.html.search] enable = false diff --git a/mdbook/spec/book.toml b/mdbook/spec/book.toml index b85e320..58dc503 100644 --- a/mdbook/spec/book.toml +++ b/mdbook/spec/book.toml @@ -25,3 +25,13 @@ theme = "../theme" "/tor-design.html" = "https://svn.torproject.org/svn/projects/design-paper/tor-design.pdf" "/walking-onions.html" = "https://spec.torproject.org/proposals/323-walking-onions-full.html" # END AUTO-GENERATED REDIRECTS + +[output.linkcheck] +warning-policy = "error" +# We effectively disable checking link destinations by excluding +# all links (`.*`). +# +# We're only using linkcheck to validate that reference-style links have *some* +# definition in the markdown, ensuring that *some* link will be generated. We +# validate that those links are correct using a separate tool (`bin/check_links`) +exclude = [ '.*' ] |