fix: hack around mdbook-linkcheck warnings by vados-cosmonic · Pull Request #224 · bytecodealliance/component-docs

vados-cosmonic · 2025-03-25T03:34:06Z

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

This commit introduces a hack that suppresses mdbook-linkcheck warnings for link-like alert constructs like `[!NOTE]`, until an upstream fix can be merged. Signed-off-by: Victor Adossi <vadossi@cosmonic.com>

itowlson · 2025-03-25T03:40:44Z

What's the issue here?

vados-cosmonic · 2025-03-25T03:43:32Z

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 · 2025-03-25T03:44:51Z

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 · 2025-03-25T03:54:06Z

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 · 2025-03-25T03:58:26Z

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 · 2025-03-25T04:00:48Z

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

fix: hack around mdbook-linkcheck warnings

f368817

This commit introduces a hack that suppresses mdbook-linkcheck warnings for link-like alert constructs like `[!NOTE]`, until an upstream fix can be merged. Signed-off-by: Victor Adossi <vadossi@cosmonic.com>

vados-cosmonic mentioned this pull request Mar 25, 2025

docs: Clarify setup for "Rust Components" tutorial #218

Merged

itowlson approved these changes Mar 25, 2025

View reviewed changes

itowlson merged commit 32b0dfd into bytecodealliance:main Mar 25, 2025

vados-cosmonic deleted the fix=hack-mdbook-link-warnings branch March 25, 2025 03:53

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix: hack around mdbook-linkcheck warnings#224

fix: hack around mdbook-linkcheck warnings#224
itowlson merged 1 commit intobytecodealliance:mainfrom
vados-cosmonic:fix=hack-mdbook-link-warnings

vados-cosmonic commented Mar 25, 2025

Uh oh!

itowlson commented Mar 25, 2025

Uh oh!

vados-cosmonic commented Mar 25, 2025 •

edited

Loading

Uh oh!

vados-cosmonic commented Mar 25, 2025

Uh oh!

itowlson left a comment

Uh oh!

vados-cosmonic commented Mar 25, 2025

Uh oh!

itowlson commented Mar 25, 2025

Uh oh!

vados-cosmonic commented Mar 25, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

vados-cosmonic commented Mar 25, 2025

Uh oh!

itowlson commented Mar 25, 2025

Uh oh!

vados-cosmonic commented Mar 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vados-cosmonic commented Mar 25, 2025

Uh oh!

itowlson left a comment

Choose a reason for hiding this comment

Uh oh!

vados-cosmonic commented Mar 25, 2025

Uh oh!

itowlson commented Mar 25, 2025

Uh oh!

vados-cosmonic commented Mar 25, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

vados-cosmonic commented Mar 25, 2025 •

edited

Loading