Read linkcheck_ignore from a project's _config.yml

[mmcky]

Split out of #2, where it was raised as a comment rather than as one of the two numbered requests. #2 shipped ignore-patterns as an explicit input; this is the follow-up idea of having the action discover the list instead.

The problem

Every QuantEcon lecture repo already maintains an exclusion list in lectures/_config.yml under sphinx.config.linkcheck_ignore, for Sphinx's own link checker. For lecture-python-programming that list holds ten accumulated false positives — fred.stlouisfed.org, keras.io, data.oecd.org, reddit.com, openai.com, chatgpt.com, an ieeexplore.ieee.org DOI, a sciencedirect.com article and a pinned matplotlib source link.

This action scans built HTML rather than running through Sphinx, so it never sees that configuration. With ignore-patterns as it shipped in #3, a repo that wants both checkers quiet has to maintain the same list twice, and the two will drift.

The proposal

Add an input pointing at the project's config file — say ignore-patterns-file: 'lectures/_config.yml' — from which the action reads sphinx.config.linkcheck_ignore and appends those patterns to whatever ignore-patterns already specifies. The patterns are regular expressions on both sides, so they carry over directly.

One list per repo instead of two, and every existing lecture repo inherits its own exclusions with a single workflow edit.

Trade-offs to weigh before building it

Consideration	Detail
New dependency	Reading YAML means adding PyYAML to requirements.txt. The action currently needs only requests and beautifulsoup4
Second configuration surface	Two places a URL can be exempted, so "why is this link not being checked?" gets harder to answer. Mitigated by logging which patterns came from where
Both routes need a workflow edit anyway	The argument that this saves work is weaker than it first appears — a repo has to add the input either way. The saving is on maintenance, not adoption
Jupyter Book 2	The lecture repos are migrating from _config.yml to myst.yml, which has no linkcheck_ignore equivalent. Anything built against the Sphinx key has a limited shelf life, and post-migration the action-level list becomes the only place to record these

That last row is the one I would decide on first. If the migration lands soon, this feature is obsolete on arrival and the effort is better spent making ignore-patterns pleasant to maintain — for example a shared list referenced from several workflows.

Semantics note

Sphinx applies linkcheck_ignore with re.match, anchored at the start of the URI. This action uses re.search, which matches anywhere. Patterns imported from a Sphinx list would therefore match slightly more here than they do under Sphinx, which is worth either normalising or documenting.

Prior art

QuantEcon/lecture-python-programming#518 tried a workflow-side workaround — rewriting matching hrefs to # in the built HTML before the checker ran. It was closed on 2026-04-14 as not the approach we want, and rightly so: mangling the build artifact to satisfy the checker also masks genuine breakage in those same files. Recording it here so it does not get re-proposed.

[mmcky]

Closing this. Researching it turned up that the premise it rests on is factually wrong, and that the component it would improve is already scheduled for replacement.

MyST does have a linkcheck_ignore equivalent

This issue and #2 both state that myst.yml has no equivalent, and that an action-level list therefore becomes the only place to record these exemptions post-migration. That is not correct. From the mystmd documentation source (jupyter-book/mystmd, docs/settings.md), under a heading titled "Ignore specific URLs":

project:
  error_rules:
    - rule: link-resolves
      severity: ignore
      keys:
        - https://flaky-connection.com
        - 'https://example.org/**'
        - 'https://*.example.com/**'

It is used in practice — mystmd's own docs/myst.yml carries a link-resolves block with eight keys. Link checking is opt-in via myst build --check-links --strict.

So the strongest argument for this feature — "there will be nowhere else to put the list" — does not hold. After migration a repo would declare exemptions natively in myst.yml, and would likely not need this action for that purpose at all.

Three differences worth recording for anyone who revisits this: MyST keys are globs, not regex; there is a separate doi-link-valid rule keyed on the DOI, which matters because 4 of the org's 18 patterns are doi.org links; and MyST already auto-skips example.com, linkedin.com, twitter.com, medium.com and wikipedia.org without any configuration.

The workflow this would improve is already earmarked for replacement

QuantEcon/project-monorepo, research/jb1-vs-jb2.md (2026-07-31), maps components from the old stack to the new. Line 76:

| linkcheck.yml | External/cross-site link validation | mystmd link checking | Verify coverage |

The same document records a dated maintainer decision that "every path ends on jb2". There is no cutover schedule, so the shelf life is real but unbounded — building a _config.yml reader would be investment in a file that disappears, inside a workflow already planned for removal.

Migration is further along than this issue assumed

QuantEcon/lecture-wasm is a fully migrated lecture repo today: lectures/ contains myst.yml and no _config.yml, it builds with myst build --html, and it does not use this action. PR QuantEcon/lecture-python-programming#363, "[Experimental] Use jupyter-book 2.0 for building the lectures", is open and was touched on 2026-08-03.

A correction to this issue's own numbers

The body says the lecture-python-programming list "holds ten accumulated false positives" and then enumerates nine. lectures/_config.yml holds nine.

What the duplication actually costs

The pain is real but small, and it now has a worked answer. QuantEcon/lecture-python-programming#592 mirrors all nine patterns into ignore-patterns with a comment saying the two lists must be kept in step; QuantEcon/lecture-python-intro#813 and QuantEcon/lecture-python-advanced.myst#370 do the same for their three and five patterns. That is nine lines duplicated in one repo, five in another, three in a third — reviewed when the exclusion list changes, which is a few times a year.

Against that: a YAML dependency, a second configuration surface, and a reader for a key that goes away. Not worth it. If the migration stalls and the duplication becomes genuinely painful, this can be reopened — the research above is the starting point.