Rebase relative links so source step docs work when viewed directly on GitHub#12
Open
pmalarme wants to merge 2 commits into
Open
Conversation
Source step docs and partials authored their relative links/images repo-root-relative, so they resolved in the rendered README but 404'd when the source doc was viewed directly on GitHub. Author them source-relative instead and rebase to repo-root-relative at render time. - render_readme.py: add rebase_relative_links() + is_rebasable_url() / resolve_relative_target() helpers; rebase step bodies and partials when composing README.md. Absolute URLs, anchors, and placeholder URLs pass through unchanged; rendered README is byte-identical. - Convert all step docs and partials to source-relative links/images. - lint_steps.py: add check K rejecting root-relative links and any link/image whose target does not exist. - Add renderer + lint tests (rebasing, absolute/anchor pass-through, image paths, root-relative and broken-link rejection). - Update workshop.instructions.md to document the new convention. Fixes #7 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Rubber-duck review flagged that normpath can collapse an over-deep `../` chain into a target starting with `..`, which the existence check could resolve outside the repo and silently pass. Flag any rebased target equal to `..` or starting with `../` as a failure so README never gets a link pointing above the repo root. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #7.
Problem
Step docs under
.workshop/docs/steps/*.mdrender into the participant's rootREADME.md, so their relative links/images were authored repo-root-relative (e.g..workshop/solutions/01-basic/,.workshop/docs/assets/01-*.png). Those resolve in the rendered README, but when a source doc is opened directly on GitHub, GitHub resolves relative links against that file's folder, so the same targets 404.Change (Option A)
../assets/…,../../solutions/…,00-intro.md#…,../steps/00-intro.md#…), so they resolve when viewed directly on GitHub.render_readme.py. Newrebase_relative_links(text, base_dir=…)(withis_rebasable_url/resolve_relative_targethelpers) rewrites relative link/image targets from source-relative to repo-root-relative when composingREADME.md. Absolute URLs (https://,mailto:), protocol-relative, pure anchors, root-absolute paths, and{{OWNER}}/{{REPO}}placeholder URLs pass through untouched; fragments and link titles are preserved. Wired into the header, footer, and step-body loaders.lint_steps.py. Rejects root-relative links and flags any link/image whose target doesn't exist (also catches stale paths like the olddocs/assets/…), scanning both step docs and partials.test_lint_steps.py(source-relative pass, root-relative rejection, broken-image rejection, real-docs green)..github/instructions/workshop.instructions.mdto document the new source-relative convention.Acceptance
README.md.python -m pytest .workshop/scripts/tests→ 103 passed;python .workshop/scripts/lint_steps.py→ 0 failures.Regression safety
The rendered
README.mdoutput is byte-identical before and after this change (verified by rendering the committedHEADdocs/scripts and the new ones and diffing) — zero participant-facing behavior change. No churn toREADME.mdor.workshop_instance/state.