Skip to content

Fix broken link checker workflow #1147

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
alexdewar merged 3 commits into from
Feb 26, 2026
+10 −8
Merged

Fix broken link checker workflow #1147

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
60c25ea
docs/model/investment.md: Fix a couple of broken links
alexdewar Feb 25, 2026
9e463b6
.lycheeignore: Suppress errors related to 404 for `erased-serde` docs
alexdewar Feb 25, 2026
237de2b
CI: Ignore `book/404.html` with link checker
alexdewar Feb 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/check-docs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,4 +19,4 @@ jobs:
id: lychee
uses: lycheeverse/lychee-action@v2
with:
args: "--verbose --no-progress --accept 200,203,503 --exclude-path ^target './**/*.md' './**/*.html'"
args: "--verbose --no-progress --accept 200,203,503 --exclude-path ^target --exclude-path ^book/404.html$ './**/*.md' './**/*.html'"
Copy link

Copilot AI Feb 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The pattern ^book/404.html$ might not match the file path as lychee sees it. The existing pattern ^target is a prefix match (no $ anchor), while your new pattern anchors to both start and end.

Depending on how lychee resolves paths, you might need ^book/404\.html$ (with escaped dot), or ^.*book/404\.html$ to allow for any prefix. Consider testing this locally to ensure it actually excludes the intended file. If it doesn't work, you might need to use .lycheeignore instead of --exclude-path.

Suggested change
args: "--verbose --no-progress --accept 200,203,503 --exclude-path ^target --exclude-path ^book/404.html$ './**/*.md' './**/*.html'"
args: "--verbose --no-progress --accept 200,203,503 --exclude-path ^target --exclude-path ^.*book/404\.html$ './**/*.md' './**/*.html'"

Copilot uses AI. Check for mistakes.
3 changes: 3 additions & 0 deletions .lycheeignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
# For some reason these spurious links appear in some cargo doc-generated files
^file://.+/MUSE2/book/api/index\.html$

# Some of these links give a 404, even though they're generated in the API docs. No idea why.
^https://docs.rs/erased-serde/

# Times out on GitHub runner
^http://www.adobe.com

Expand Down
13 changes: 6 additions & 7 deletions docs/model/investment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,10 @@
<!-- markdownlint-disable MD049 -->

This section details the investment and asset retention decision process, which is applied within
step 2 of the [overall MUSE2 workflow]. This process determines which new assets to build and
which existing assets to retain to meet system needs over time. In the overall workflow, dispatch
optimisation is used to identify *physical needs* by quantifying demand profiles for commodities of
interest.
step 2 of the [overall MUSE2 workflow][framework-overview]. This process determines which new assets
to build and which existing assets to retain to meet system needs over time. In the overall
workflow, dispatch optimisation is used to identify *physical needs* by quantifying demand profiles
for commodities of interest.

## Commodity prices

Expand All @@ -23,7 +23,7 @@ the preceding MSY. When the `pricing_strategy` option is set to `scarcity_adjust
shadow prices for each commodity adjusted to remove the impact of binding capacity constraints.

Note: there is an option to iterate over each year so that investment decisions are based on
equilibrium prices in the _current year_, in what's referred to as the "[ironing-out loop]".
equilibrium prices in the _current year_, in what's referred to as the "[ironing-out loop][framework-overview]".
In this case, \\( \lambda\_{c,r,t} \\) will reflect prices from previous iteration of the
ironing-out loop.

Expand Down Expand Up @@ -203,6 +203,5 @@ For each asset option:
AFC \* cap_r + \sum_{t} act_t \* AC_t \\)), divided by the annual output
\\( \sum_t act_t \\).

[overall MUSE2 workflow]: ./README.md#framework-overview
[framework-overview]: https://energysystemsmodellinglab.github.io/MUSE2/model/index.html#framework-overview
Copy link
Collaborator

@tsmbland tsmbland Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why do we have to use a URL here rather than an internal link?

Copy link

Copilot AI Feb 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Using an absolute URL to the published documentation creates a hard dependency on the documentation hosting location and won't work for local builds or forks.

The better approach would be to use a relative path that works with mdBook's build system. Since model/README.md becomes model/index.html when built, you could try:

  • ./README.md#framework-overview (should work in raw markdown and mdBook)
  • Or configure the link checker to understand mdBook's README→index.html transformation

The current absolute URL will break if the documentation is ever moved to a different domain or viewed locally, and it creates an external dependency where an internal link would suffice.

Suggested change
[framework-overview]: https://energysystemsmodellinglab.github.io/MUSE2/model/index.html#framework-overview
[framework-overview]: ./README.md#framework-overview

Copilot uses AI. Check for mistakes.
[Dispatch Optimisation Formulation]: ./dispatch_optimisation.md
[ironing-out loop]: ./README.md#framework-overview
Loading