Azure-Samples / Azure-Samples/foundry-hosted-agents-workshop
Renderer: rebase relative links so source step docs work when viewed directly on GitHub
- Dominant language
- Python
- Stars
- 7
- Forks
- 7
- Avg merge
- 2h 59m
- Merged PRs (30d)
- 3
Description
## 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)
1. Author source docs with **source-relative** links/images (`../assets/...`, `../../solutions/...`) so they resolve when viewing the source doc directly on GitHub.
2. 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.
3. 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).
4. 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._
Contributor guide
Research direction
Start by reading .workshop/scripts/render_readme.py and lint_steps.py, then inspect the tests under .workshop/scripts/tests. Trace how step-document links and images are composed into README.md, and use the stated cases for relative links, absolute URLs, anchors, and images as the completion checklist. Run python -m pytest .workshop/scripts/tests and python .workshop/scripts/lint_steps.py to verify the acceptance criteria.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation, testing, tooling
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100