Builds are failing due to link problems

[brian-rose]

Since we implemented the --strict build option (ProjectPythia/cookbook-actions#160), builds are now failing for the portal site due to link issues:

about.md
  - Link for "https://docs.google.com/presentation/d/1D8kkpsX4CE3rT5QQliH6JfKYeY76fT1gClIEzboxgko/" did not resolve. (401, Unauthorized)


posts/2025/mystification.md
  - Link for "https://next.jupyterbook.org/" did not resolve.


posts/2025/new-cookbooks.md
  - Link has no URL: SAVE THE DATE! Project Pythia is hosting our next Cookbook Cook-off hackathon event at the NSF NCAR's Mesa Lab, August 5-8 2025.
  - Link for "@mgrover1" did not resolve.
  - Link for "@nocollier" did not resolve.
  - Link for "@cehbrecht" did not resolve.
  - Link for "@jacnugent" did not resolve.
  - Link for "@griverat" did not resolve.
  - Link for "" did not resolve.


Site has 15 errors and 3 warnings, stopping build.
contributing.md
  - Link for "https://projectpythia.org/code_of_conduct" did not resolve. (404, Not Found)
  - Link for "https://github.com/YOUR_USER_NAME/pythia-foundations" did not resolve. (404, Not Found)
  - Link for "https://github.com/YOUR_USER_NAME/pythia-foundations" did not resolve. (404, Not Found)


cookbook-guide.md
  - Link for "http://localhost:3000" did not resolve.


metrics.md
  - unexpected figure content of type output found in legend node
  - unexpected figure content of type output found in legend node
  - unexpected figure content of type output found in legend node


/home/runner/work/projectpythia.github.io/projectpythia.github.io/CODEOFCONDUCT.md
  - Link for "chro@ucar.edu" did not resolve.
  - Link for "chro@ucar.edu" did not resolve.

[jukent]

I'm not sure if MyST currently separating out these two types of failures. Hopefully we can update this when they do.

In the mean time I think we need to leverage error rules:

project:
  error_rules:
    - rule: link-resolves
      severity: ignore
      keys:
        - '*@ucar.edu'
        - 'http://localhost:3000'
        - 'https://github.com/YOUR_USER_NAME/pythia-foundations'
        - ''
        - '@*'

to specify links we know aren't going to pass

[jukent]

Running myst --debug build might allow us to separate out the build and link checking rules?

[dcamron]

I'm glad to ping the myst folks to ask about separating link checking out of --strict by default. Whether we get that or not, it sounds like we will fail workflows with failing links; ie, if we separate link checking out and it still works, all our workflows that check links at the same time that they build will fail anyway. Leading up to the hackathon, how would y'all prefer to address this? Some options come to my mind:

1. Disable link checking altogether and leave strict builds enabled (only works if myst lets us separate)
2. Revert strict builds
3. Fix broken links where we can and add default excludes to our base config. Note that if I read the documentation correctly, adding excludes will force them to be ignored even in myst build --link-check --strict. Possibly nontrivial for existing Cookbooks
4. Allow non-strict builds on PR preview workflow, and require strict builds to merge PR or on push to main. This could be nontrivial to implement on existing Cookbooks, but I'm not sure
5. Something else of y'all's suggestion

[jukent]

Thanks @dcamron I made some changes in #566 (still failing with the metrics, might want another pair of eyes later).

But I did confirm in my local build that the project: error-rules: is not superseded by the --strict build flag.

1. Still checks links just not as a separate job, yes?
2. If we go this route, maybe we leave them up for ~1 week to see have loud failures that are easier to diagnose and fix before reverting?
3. This sounds like what I did above, I think we'll go this route regardless of whether we can separate link checker from the nightly build check.
4. I don't think this solves the issues of us not seeing/knowing that something is failing several months or years after it is merged into the gallery.

[dcamron]

If we don't have many broken cookbooks elsewhere off this then your work with (3) makes the most sense to me! We can eventually separate if needed. I think we only choose (2) if there are now lots of build failures across all existing Cookbooks, and I agree with leaving it up to signal needed maintenance.

Also for (4) I think it still does help us catch broken builds, but I realize it does not address the issue here, so ignore it for now. Tangential thought 😂

[jukent]

I'm trying to work my way through all the build failures. I made this spreadsheet to keep track of the PRs cross all our different repositories. I'll ping the team again once I've made more progress.