Azure-Samples / Azure-Samples/foundry-hosted-agents-workshop

Renderer: rebase relative links so source step docs work when viewed directly on GitHub

Open
#7 0 comments 0 reactions 0 assignees View on GitHub
enhancement
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.