Repository navigation
Build warnings: missing source files, broken cross-references, footnote ID mismatch, and external link failures #6
Description
Description
The CI build (docs.yml) produces 41 warnings. After verifying against the source code, the root causes are as follows.
https://github.com/theopensourceway/production/actions/runs/26198396307/job/77082787146
Category 1: Missing source files (2 files)
Two cross-reference targets do not exist in the guidebook repository:
getting-started/creating-an-open-source-product-strategy.md— MISSINGgetting-started/setting-goals.md— MISSING
These are referenced in essentials-of-building-a-community.md (lines 42, 58, 73) but have never been created. This is a content gap in the guidebook.
Fix: Create these files in the guidebook repository, or remove/update the references if the content has been folded into other chapters.
Category 2: Cross-reference path resolution (12 warnings for existing files)
Cross-references like [text](getting-started/community-101.md) from within getting-started/essentials-of-building-a-community.md produce warnings even though the target files exist.
Root cause: The source uses directory-prefixed paths (e.g., getting-started/community-101.md) from within the same directory. Since the referencing file is already in getting-started/, MyST resolves getting-started/community-101.md relative to the current document as getting-started/getting-started/community-101.md, which does not exist. The correct relative reference would be just community-101.md (or community-101 without the .md extension).
Similarly, [text](../measuring-success/defining-healthy-communities.md) from getting-started/ works because the ../ correctly navigates up one level.
Affected file: getting-started/essentials-of-building-a-community.md — 11 references with incorrect relative paths. Also getting-started/building-a-strategy.md — 1 reference with incorrect path.
Fix: In the guidebook repository, update the cross-reference paths to be correctly relative to the current file's location. For example:
[community](getting-started/community-101.md)→[community](community-101.md)- Alternatively, use MyST's explicit cross-reference syntax:
{doc}`community-101`
Category 3: Footnote ID mismatch (22 warnings)
All 22 warnings are in community-manager-self-care.md, of the form:
WARNING: 'myst' cross-reference target not found: 'user-content-fn-1' [myst.xref_missing]
Root cause: The source uses [^1] footnote syntax, which MyST renders with user-content-fn-* IDs (a GitBook convention that MyST's markdown-it parser preserves). However, Sphinx's cross-reference resolver does not register these IDs as valid targets, so it reports them as missing.
The footnotes render correctly in the HTML output — the references and back-references work. The warnings are false positives from MyST's cross-reference validation, but they clutter the build log and may mask real issues.
Fix (options):
- Add
user-content-fn-*patterns tomyst_xref_missingsuppression inconf.py:myst_xref_missing_suppress = [r"user-content-fn-\d+"]
- Configure MyST to use Sphinx-native footnote IDs instead of GitBook-style IDs
- Suppress the specific warning type in
conf.py:suppress_warnings = ["myst.xref_missing"]
Category 4: Broken external links (15 links — 403/404 errors)
404 Not Found (2 links)
| Source file | URL |
|---|---|
| building-diverse-open-source-communities... | https://www2.deloitte.com/au/en/blog/diversity-inclusion-blog/2019/meritocracy-unraveling-paradox.html |
| defining-healthy-communities | https://github.com/theopensourceway/guidebook/blob/master/worksheet_for_community_audits.ods |
403 Forbidden — likely blocks automated requests (11 links)
Anchor not found (1 link)
| Source file | URL |
|---|---|
| building-diverse-open-source-communities... | https://insights.stackoverflow.com/survey/2019#... (text fragment anchor) |
Note: Many 403 errors are from sites that block automated requests but may be accessible in a browser. Options:
- Find alternative/archive URLs (e.g., Wayback Machine)
- Add known-403 patterns to
linkcheck_ignoreinconf.py - Replace with local references or cached content
Fix location: guidebook repository — update or replace broken URLs. production repository — add linkcheck_ignore patterns for sites that consistently block CI.
Category 5: Permanent redirects (14 links — should be updated)
Fix location: guidebook repository — update URLs to their current targets.
Action items
guidebook repository (requires maintainer action)
- Create missing files:
creating-an-open-source-product-strategy.md,setting-goals.md(or remove references) - Fix cross-reference paths in
essentials-of-building-a-community.mdandbuilding-a-strategy.md - Update or replace broken external links (403/404)
- Update redirected URLs to their current targets
production repository (can be done by production team)
- Suppress footnote cross-reference warnings in
conf.py - Add
linkcheck_ignorepatterns for sites that consistently block CI
Activity
sanchuanhehe commentedon May 23, 2026
@semioticrobotic I've verified the root causes against the source code. A few items here need your help as guidebook maintainer:
creating-an-open-source-product-strategy.mdandsetting-goals.md) don't exist in the repo. Should they be created, or have they been folded into other chapters and the references should be removed?essentials-of-building-a-community.mdandbuilding-a-strategy.mduse directory-prefixed paths from within the same directory (e.g.,getting-started/community-101.md), which MyST resolves incorrectly. These need to be updated to relative paths. I can submit a PR if you'd like.The footnote warnings (Category 3) can be handled on the production side. Happy to help with PRs for any of the above.
semioticrobotic commentedon May 26, 2026
Thanks very much, @sanchuanhehe.
I have created the
fix-buildsbranch to begin addressing these issues. Here are some notes from me.Category 1
These should now be resolved. These were links to two chapters that have since combined intoa single chapter.
Category 2
I believe I've fixed all cross-references. Please let me know if not.
Category 3
This will take a little more time. Reformatting these footnotes is something I have been wanting to do, just have not yet gotten to it. I have opened theopensourceway/guidebook#262 as a work item.
Category 4
I have opened an issue to address the missing worksheet file (see theopensourceway/guidebook#263). I am not quite certain how to address the other links. They resolve when I navigate tot hem manually, of course, but that is not the issue. Would the
linkcheck_ignorework?Category 5
I have updated redirects with the new target URLs.
Not sure if you can perform a dry run against my branch, but if so perhaps give that a try to see if this resolves the majority of the issues.
(Note that I have made the above changes only in the English versions of the source files.)
sanchuanhehe commentedon May 27, 2026
Thanks for the quick response and the fixes!
Category 4 — Yes,
linkcheck_ignorewill work for those URLs. I'll add the patterns to the productionconf.py. It's likely a CI environment issue (Microsoft-hosted runners or similar) rather than the links themselves being broken.Category 5 — Great, thanks for updating those.
I'll try to run a build against your
fix-buildsbranch this weekend and let you know how it goes. I'll also make sure the Chinese.pofiles are updated to match the English source changes.sanchuanhehe commentedon Jun 11, 2026
@semioticrobotic I ran a local build against your
fix-buildsbranch (guidebook submodule) with the production toolchain. Great results:English HTML build: 41 warnings → 0 warnings (
build succeeded.)building-a-strategy.md)getting-started/X.md→X.md, cross-dir links use../)[…](#user-content-fn-N)links, leaving clean[^N]footnotes. No suppression needed on the production side after all. (Tracking the fuller reformat in guidebook#262.)One small typo to fix in
getting-started/essentials-of-building-a-community.md(line 37) — an unbalanced parenthesis was introduced when thegetting-started/prefix was removed:should be:
(Doesn't affect the build, but a stray
(renders in the output.)Production side (Category 4): I'm opening a PR to add
linkcheck_ignorepatterns for the sites that 403 in CI (bls.gov, nytimes.com, wiley.com, academic.oup.com, huffpost.com, mayoclinic.org, etc.). These resolve fine in a browser — it's the CI runner being blocked. The worksheet 404 stays tracked in guidebook#263, and the Deloitte 404 + the Stack Overflow text-fragment anchor are genuine link issues better fixed in the source.zh_CN translations: since you changed only the English source, I'll resync the
.pomsgids (footnotes/cross-refs changed the translatable units) oncefix-buildsis merged tomain, so they don't drift against the branch.ci: add linkcheck_ignore for CI-blocked external links (#6, Category …
semioticrobotic commentedon Jun 11, 2026
Thanks, @sanchuanhehe! Great work here. I'm glad my changes helped.
I have fixed this. Thanks for the catch!
I will merge
fix-builds. Please review and, if all looks good, feel free to close this issue. Thanks for the great teamwork. 🤝i18n: resync zh_CN catalogs with guidebook build fixes (#6) (#10)
sanchuanhehe commentedon Jun 13, 2026
Resolved across both repos. ✅
guidebook (@semioticrobotic,
build: remediate various build errors):building-a-strategy.md(#user-content-fn-N)links, leaving clean[^N]production:
linkcheck_ignorefor CI-blocked (403) domains (ci: add linkcheck_ignore for CI-blocked external links (#6 Category 4) #9)Result: English and zh_CN both build with 0 warnings (was 41), PDF builds pass, and the catalog consistency check is idempotent.
Remaining genuine link issues are tracked separately:
worksheet_for_community_audits.ods→ guidebook#263Thanks for the great teamwork, @semioticrobotic! 🤝