Build warnings: missing source files, broken cross-references, footnote ID mismatch, and external link failures

[sanchuanhehe]

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 — MISSING
• getting-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):

1. Add user-content-fn-* patterns to myst_xref_missing suppression in conf.py:

   myst_xref_missing_suppress = [r"user-content-fn-\d+"]

2. Configure MyST to use Sphinx-native footnote IDs instead of GitBook-style IDs
3. 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)

Source file	URL
building-diverse-open-source-communities...	https://www.bls.gov/cps/cpsaat11.htm
building-diverse-open-source-communities...	https://www.nytimes.com/2020/07/11/...
building-diverse-open-source-communities...	https://www.unwomen.org/en/news/in-focus/csw61/redistribute-unpaid-work
building-diverse-open-source-communities...	https://www.weforum.org/agenda/2019/03/...
community-manager-self-care	https://academic.oup.com/occmed/article/69/1/35/5151234
community-manager-self-care	https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1365-2702.2011.03868.x
community-manager-self-care	https://spssi.onlinelibrary.wiley.com/doi/abs/10.1111/j.1540-4560.1974.tb00706.x
community-manager-self-care	https://www.huffpost.com/entry/in-control-vs-under-control-leadership_b_12590650
community-manager-self-care	https://www.managers.org.uk/insights/news/2019/september/how-to-talk-about-depression-at-work
community-manager-self-care	https://www.mayoclinic.org/healthy-lifestyle/stress-management/in-depth/social-support/art-20044445
community-manager-self-care	https://www.teamblind.com/blog/...
community-manager-self-care	https://www.theburnoutproject.com.au/product/burnoutbookpaperback/
project-and-community-governance	https://www.opavote.com/

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_ignore in conf.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)

URL	Redirects to
http://kubernetes.io/	https://kubernetes.io/
http://credit.niso.org/	https://credit.niso.org/
https://about.gitlab.com/job-families/expert/merge-request-coach/	https://handbook.gitlab.com/job-description-library/expert/merge-request-coach/
https://docs.gitlab.com/ee/user/project/description_templates.html	https://docs.gitlab.com/user/project/description_templates/
https://docs.github.com/en/github/building-a-strong-community/configuring-issue-templates-for-your-repository	https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository
https://github.com/kubernetes/community/tree/master/sig-contributor-experience	https://github.com/kubernetes/community/tree/main/sig-contributor-experience
https://theopensourceway.org	https://www.theopensourceway.org/
https://www.apa.org/topics/manage-stress-social-support	https://www.apa.org/topics/stress/manage-social-support
https://www.mentalhealth.org.uk/campaigns/mental-health-awareness-week	https://www.mentalhealth.org.uk/our-work/public-engagement/mental-health-awareness-week
https://www.mentorship.guide/	https://mentorship.guide/
https://www.python.org/dev/peps/pep-0008/	https://peps.python.org/pep-0008/
https://www.who.int/mental_health/evidence/burn-out/en/	https://www.who.int/news/item/28-05-2019-burn-out-an-occupational-phenomenon-international-classification-of-diseases
https://www.psychologytoday.com/...the-heavy-price-high-achievement	...the-heavy-price-of-high-achievement
https://www.karenhixsonlpc.com/	https://www.drhixson.com/

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.md and building-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_ignore patterns for sites that consistently block CI

[sanchuanhehe]

@semioticrobotic I've verified the root causes against the source code. A few items here need your help as guidebook maintainer:

• Two referenced files (creating-an-open-source-product-strategy.md and setting-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?
• Cross-reference paths in essentials-of-building-a-community.md and building-a-strategy.md use 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.
• Broken and redirected external links need updating in the guidebook source. I can prepare a PR for the straightforward ones.

The footnote warnings (Category 3) can be handled on the production side. Happy to help with PRs for any of the above.

[semioticrobotic]

Thanks very much, @sanchuanhehe.

I have created the fix-builds branch 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_ignore work?

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]

Thanks for the quick response and the fixes!

Category 4 — Yes, linkcheck_ignore will work for those URLs. I'll add the patterns to the production conf.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-builds branch this weekend and let you know how it goes. I'll also make sure the Chinese .po files are updated to match the English source changes.

[sanchuanhehe]

@semioticrobotic I ran a local build against your fix-builds branch (guidebook submodule) with the production toolchain. Great results:

English HTML build: 41 warnings → 0 warnings (build succeeded.)

Category	Status
1 — Missing files	Resolved (references now point to the combined building-a-strategy.md)
2 — Cross-reference paths	Resolved (getting-started/X.md → X.md, cross-dir links use ../)
3 — Footnote IDs	Resolved — you removed the duplicate […](#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.)
5 — Redirects	Updated to current targets

One small typo to fix in getting-started/essentials-of-building-a-community.md (line 37) — an unbalanced parenthesis was introduced when the getting-started/ prefix was removed:

...grow collaboratively ([community](community-101.md).

should be:

...grow collaboratively ([community](community-101.md)).

(Doesn't affect the build, but a stray ( renders in the output.)

Production side (Category 4): I'm opening a PR to add linkcheck_ignore patterns 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 .po msgids (footnotes/cross-refs changed the translatable units) once fix-builds is merged to main, so they don't drift against the branch.

[semioticrobotic]

Thanks, @sanchuanhehe! Great work here. I'm glad my changes helped.

One small typo to fix in getting-started/essentials-of-building-a-community.md (line 37) — an unbalanced parenthesis was introduced when the getting-started/ prefix was removed.

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. 🤝