fix: hack around mdbook-linkcheck warnings

[vados-cosmonic]

This commit introduces a hack that suppresses mdbook-linkcheck warnings for link-like alert constructs like [!NOTE], until an upstream fix can be merged.

[itowlson]

What's the issue here?

[vados-cosmonic]

Ah the issue here is that mdbook-linkcheck produces a ton of warnings for link-like alert constructs like [!NOTE] which aren't real errors, but DO obscure real errors.

Before

mdbook build
2025-03-25 12:42:04 [INFO] (mdbook::book): Book building has started
2025-03-25 12:42:04 [INFO] (mdbook::book): Running the html backend
2025-03-25 12:42:04 [INFO] (mdbook::book): Running the linkcheck backend
2025-03-25 12:42:04 [INFO] (mdbook::renderer): Invoking the "linkcheck" renderer
warning: Potential incomplete link
   ┌─ language-support/c.md:88:3
   │
88 │ > [!NOTE]
   │   ^^^^^^^ Did you forget to define a URL for `!NOTE`?
   │
   = hint: declare the link's URL. For example: `[!NOTE]: http://example.com/`

warning: Potential incomplete link
    ┌─ language-support/c.md:168:3
    │
168 │ > [!WARNING]
    │   ^^^^^^^^^^ Did you forget to define a URL for `!WARNING`?
    │
    = hint: declare the link's URL. For example: `[!WARNING]: http://example.com/`

warning: Potential incomplete link
    ┌─ language-support/c.md:174:3
    │
174 │ > [!NOTE]
    │   ^^^^^^^ Did you forget to define a URL for `!NOTE`?
    │
    = hint: declare the link's URL. For example: `[!NOTE]: http://example.com/`

warning: Potential incomplete link
    ┌─ language-support/csharp.md:117:3
    │
117 │ > [!WARNING]
    │   ^^^^^^^^^^ Did you forget to define a URL for `!WARNING`?
    │
    = hint: declare the link's URL. For example: `[!WARNING]: http://example.com/`

warning: Potential incomplete link
    ┌─ language-support/csharp.md:121:29
    │
121 │ This repository contains an [example WebAssembly host][example-host] written in Rust that can run components that implement the `adder` world.
    │                             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Did you forget to define a URL for `example-host`?
    │
    = hint: declare the link's URL. For example: `[example-host]: http://example.com/`

warning: Potential incomplete link
    ┌─ language-support/csharp.md:123:3
    │
123 │ > [!NOTE]
    │   ^^^^^^^ Did you forget to define a URL for `!NOTE`?
    │
    = hint: declare the link's URL. For example: `[!NOTE]: http://example.com/`

warning: Potential incomplete link
   ┌─ language-support/go.md:16:3
   │
16 │ > [!WARNING]
   │   ^^^^^^^^^^ Did you forget to define a URL for `!WARNING`?
   │
   = hint: declare the link's URL. For example: `[!WARNING]: http://example.com/`

warning: Potential incomplete link
   ┌─ language-support/go.md:52:3
   │
52 │ > [!NOTE]
   │   ^^^^^^^ Did you forget to define a URL for `!NOTE`?
   │
   = hint: declare the link's URL. For example: `[!NOTE]: http://example.com/`

warning: Potential incomplete link
    ┌─ language-support/go.md:111:3
    │
111 │ > [!NOTE]
    │   ^^^^^^^ Did you forget to define a URL for `!NOTE`?
    │
    = hint: declare the link's URL. For example: `[!NOTE]: http://example.com/`

warning: Potential incomplete link
   ┌─ language-support/javascript.md:12:3
   │
12 │ > [!WARNING]
   │   ^^^^^^^^^^ Did you forget to define a URL for `!WARNING`?
   │
   = hint: declare the link's URL. For example: `[!WARNING]: http://example.com/`

warning: Potential incomplete link
   ┌─ language-support/javascript.md:30:3
   │
30 │ > [!NOTE]
   │   ^^^^^^^ Did you forget to define a URL for `!NOTE`?
   │
   = hint: declare the link's URL. For example: `[!NOTE]: http://example.com/`

warning: Potential incomplete link
   ┌─ language-support/javascript.md:60:3
   │
60 │ > [!NOTE]
   │   ^^^^^^^ Did you forget to define a URL for `!NOTE`?
   │
   = hint: declare the link's URL. For example: `[!NOTE]: http://example.com/`

warning: Potential incomplete link
   ┌─ language-support/javascript.md:80:3
   │
80 │ > [!WARNING]
   │   ^^^^^^^^^^ Did you forget to define a URL for `!WARNING`?
   │
   = hint: declare the link's URL. For example: `[!WARNING]: http://example.com/`

warning: Potential incomplete link
    ┌─ language-support/javascript.md:100:3
    │
100 │ > [!NOTE]
    │   ^^^^^^^ Did you forget to define a URL for `!NOTE`?
    │
    = hint: declare the link's URL. For example: `[!NOTE]: http://example.com/`

warning: Potential incomplete link
    ┌─ language-support/javascript.md:121:3
    │
121 │ > [!WARNING]
    │   ^^^^^^^^^^ Did you forget to define a URL for `!WARNING`?
    │
    = hint: declare the link's URL. For example: `[!WARNING]: http://example.com/`

warning: Potential incomplete link
    ┌─ language-support/javascript.md:178:3
    │
178 │ > [!NOTE]
    │   ^^^^^^^ Did you forget to define a URL for `!NOTE`?
    │
    = hint: declare the link's URL. For example: `[!NOTE]: http://example.com/`

warning: Potential incomplete link
    ┌─ language-support/javascript.md:258:3
    │
258 │ > [!WARNING]
    │   ^^^^^^^^^^ Did you forget to define a URL for `!WARNING`?
    │
    = hint: declare the link's URL. For example: `[!WARNING]: http://example.com/`

warning: Potential incomplete link
    ┌─ language-support/javascript.md:289:3
    │
289 │ > [!NOTE]
    │   ^^^^^^^ Did you forget to define a URL for `!NOTE`?
    │
    = hint: declare the link's URL. For example: `[!NOTE]: http://example.com/`

warning: Potential incomplete link
    ┌─ language-support/javascript.md:303:3
    │
303 │ > [!NOTE]
    │   ^^^^^^^ Did you forget to define a URL for `!NOTE`?
    │
    = hint: declare the link's URL. For example: `[!NOTE]: http://example.com/`

warning: Potential incomplete link
    ┌─ language-support/javascript.md:332:3
    │
332 │ > [!TIP]
    │   ^^^^^^ Did you forget to define a URL for `!TIP`?
    │
    = hint: declare the link's URL. For example: `[!TIP]: http://example.com/`

warning: Potential incomplete link
    ┌─ language-support/javascript.md:348:3
    │
348 │ > [!NOTE]
    │   ^^^^^^^ Did you forget to define a URL for `!NOTE`?
    │
    = hint: declare the link's URL. For example: `[!NOTE]: http://example.com/`

warning: Potential incomplete link
    ┌─ language-support/javascript.md:407:3
    │
407 │ > [!NOTE]
    │   ^^^^^^^ Did you forget to define a URL for `!NOTE`?
    │
    = hint: declare the link's URL. For example: `[!NOTE]: http://example.com/`

warning: Potential incomplete link
    ┌─ language-support/javascript.md:483:3
    │
483 │ > [!NOTE]
    │   ^^^^^^^ Did you forget to define a URL for `!NOTE`?
    │
    = hint: declare the link's URL. For example: `[!NOTE]: http://example.com/`

warning: Potential incomplete link
    ┌─ language-support/javascript.md:504:3
    │
504 │ > [!NOTE]
    │   ^^^^^^^ Did you forget to define a URL for `!NOTE`?
    │
    = hint: declare the link's URL. For example: `[!NOTE]: http://example.com/`

warning: Potential incomplete link
    ┌─ language-support/javascript.md:519:3
    │
519 │ > [!TIP]
    │   ^^^^^^ Did you forget to define a URL for `!TIP`?
    │
    = hint: declare the link's URL. For example: `[!TIP]: http://example.com/`

warning: Potential incomplete link
    ┌─ language-support/javascript.md:540:3
    │
540 │ > [!NOTE]
    │   ^^^^^^^ Did you forget to define a URL for `!NOTE`?
    │
    = hint: declare the link's URL. For example: `[!NOTE]: http://example.com/`

warning: Potential incomplete link
   ┌─ language-support/python.md:35:3
   │
35 │ > [!NOTE]
   │   ^^^^^^^ Did you forget to define a URL for `!NOTE`?
   │
   = hint: declare the link's URL. For example: `[!NOTE]: http://example.com/`

(NOTE: there's a "real" error tucked in the before output above :)

After

mdbook build
2025-03-25 12:41:40 [INFO] (mdbook::book): Book building has started
2025-03-25 12:41:40 [INFO] (mdbook::book): Running the html backend
2025-03-25 12:41:40 [INFO] (mdbook::book): Running the linkcheck backend
2025-03-25 12:41:40 [INFO] (mdbook::renderer): Invoking the "linkcheck" renderer

[vados-cosmonic]

Ah also relevant -- this came up while working on #218 (comment) (would appreciate reviews/attention there!)

[itowlson]

Thanks for explaining! I'm good to go with this as long as it doesn't affect the rendered output.

[vados-cosmonic]

Yeah that's a really good point -- I made sure to check locally. At least in my browser, everything renders properly still and the warning boxes are warnings/etc.

[itowlson]

Build is now failing with:

Error: -25 03:53:32 [ERROR] (mdbook::renderer): The command `mdbook-linkcheck` wasn't found, is the "linkcheck" backend installed? If you want to ignore this error when the "linkcheck" backend is not installed, set `optional = true` in the `[output.linkcheck]` section of the book.toml configuration file.
Error: -25 03:53:32 [ERROR] (mdbook::utils): Error: Rendering failed
Error: -25 03:53:32 [ERROR] (mdbook::utils): 	Caused By: Unable to start the backend
Error: -25 03:53:32 [ERROR] (mdbook::utils): 	Caused By: No such file or directory (os error 2)

Although I don't get how that can be related...?

[vados-cosmonic]

That's definitely odd -- is it possible that CI error is different/unrelated? is it possible mdbook-linkcheck is just not installed in CI?