Problem
Step docs under .workshop/docs/steps/*.md render into the participant's root README.md, so their relative links and images are authored repo-root-relative (e.g. .workshop/docs/assets/01-*.png, .workshop/solutions/01-basic/). Those resolve correctly in the rendered README.
However, when a maintainer or participant opens a source step doc directly on GitHub (e.g. .workshop/docs/steps/01-basic.md), GitHub resolves relative links against that file's folder, so .workshop/solutions/01-basic/ becomes .workshop/docs/steps/.workshop/solutions/01-basic/ → 404. This predates the .workshop/ restructure (it was equally broken before at docs/steps/), but the restructure is a good moment to capture the fix.
This is the shared root cause behind a class of link bugs — e.g. stale docs/assets/... image links that only surfaced during the restructure review.
Current mitigation
Documented the root-relative convention in .github/instructions/workshop.instructions.md (source docs are authored for the rendered README; direct source viewing shows broken relative links by design). No behavior change.
Proposed enhancement (Option A)
- Author source docs with source-relative links/images (
../assets/..., ../../solutions/...) so they resolve when viewing the source doc directly on GitHub.
- Add a rebasing pass in
.workshop/scripts/render_readme.py that rewrites relative links/images from "relative to .workshop/docs/steps/" to "relative to repo root" when composing README.md. Must leave absolute URLs (https://...) and pure #anchor links untouched.
- Add a lint rule in
.workshop/scripts/lint_steps.py that rejects root-relative links in source docs (enforces the new convention), and ideally a link/image existence checker (which would also have caught the stale docs/assets/... links automatically).
- Add renderer + lint tests covering: relative link rebasing, absolute-URL pass-through, anchor pass-through, and image paths.
Acceptance
- Source step docs render valid links both when viewed directly on GitHub and when inlined into the root
README.md.
- Lint fails on root-relative links and on links/images that point at non-existent targets.
python -m pytest .workshop/scripts/tests and python .workshop/scripts/lint_steps.py stay green.
Migrated from pmalarme/foundry-workshop-template#69.
Problem
Step docs under
.workshop/docs/steps/*.mdrender into the participant's rootREADME.md, so their relative links and images are authored repo-root-relative (e.g..workshop/docs/assets/01-*.png,.workshop/solutions/01-basic/). Those resolve correctly in the rendered README.However, when a maintainer or participant opens a source step doc directly on GitHub (e.g.
.workshop/docs/steps/01-basic.md), GitHub resolves relative links against that file's folder, so.workshop/solutions/01-basic/becomes.workshop/docs/steps/.workshop/solutions/01-basic/→ 404. This predates the.workshop/restructure (it was equally broken before atdocs/steps/), but the restructure is a good moment to capture the fix.This is the shared root cause behind a class of link bugs — e.g. stale
docs/assets/...image links that only surfaced during the restructure review.Current mitigation
Documented the root-relative convention in
.github/instructions/workshop.instructions.md(source docs are authored for the rendered README; direct source viewing shows broken relative links by design). No behavior change.Proposed enhancement (Option A)
../assets/...,../../solutions/...) so they resolve when viewing the source doc directly on GitHub..workshop/scripts/render_readme.pythat rewrites relative links/images from "relative to.workshop/docs/steps/" to "relative to repo root" when composingREADME.md. Must leave absolute URLs (https://...) and pure#anchorlinks untouched..workshop/scripts/lint_steps.pythat rejects root-relative links in source docs (enforces the new convention), and ideally a link/image existence checker (which would also have caught the staledocs/assets/...links automatically).Acceptance
README.md.python -m pytest .workshop/scripts/testsandpython .workshop/scripts/lint_steps.pystay green.Migrated from pmalarme/foundry-workshop-template#69.