docs: Add local PR preview workflow#74
Open
andmatei wants to merge 8 commits into
Open
Conversation
Add scripts/preview-pr.sh, which checks out a PR (via the GitHub CLI) and starts the Docusaurus dev server, document the reviewer flow in CONTRIBUTING.md, and add a preview-ipa Claude Code skill that wraps it. Reviewers can see how guideline enrichments render before approving without hosted preview infrastructure; this complements the existing CI build, which already fails on broken links (onBrokenLinks: throw).
Add a thin .claude/commands/preview-pr.md that delegates to the preview-ipa skill (the workspace command->skill->script pattern), and add an argument-hint to the skill to match the staging-preview convention.
Add a --port/-p option (and --port=N) to scripts/preview-pr.sh so reviewers can avoid a clash on port 3000 (e.g. comparing two PRs) and so a backgrounded run doesn't stall on Docusaurus's interactive 'port in use' prompt. Document it in CONTRIBUTING.md and the preview-ipa skill.
- skill: stop the dev server by killing the process tree (a lone kill orphans the node server and leaves the port bound) - script + skill: add --no-open and use it on the backgrounded run so it doesn't pop a browser tab - script: --port= (empty value) now errors like the bare --port form - skill + command: report the actual port instead of hardcoding 3000
The site's baseUrl is /ipa/, so a guideline renders at http://localhost:<port>/ipa/<id> (id = the IPA number from frontmatter, e.g. ipa/general/0101.mdx -> /ipa/101), not /<id>. Verified against the production build output. Fixes the URL mapping in the skill, command, and CONTRIBUTING.
Lead the description with 'Use when' triggers only (drop the what-it-does summary), dedupe the port guidance (was in both step 2 and Notes), push flag details to --help, and tighten prose. No change to the documented workflow.
…aware - Don't restate the Node/npm version in the skill or script header; .tool-versions is the source of truth and a hardcoded copy would drift on a version bump. - Trim the CONTRIBUTING 'Reviewing a PR locally' section. - Report URLs as http://localhost:<port>/ipa/... instead of hardcoding 3000, since --port can change it.
The helper script is the documented path and Development Setup already covers npm ci + docusaurus:start, so the by-hand line was redundant.
andmatei
changed the title
andmatei
requested review from
andreaangiolillo,
drinkbird,
lovisaberggren,
maks-m-mongo-leaf,
matt-condon,
saisundar and
wtrocki
yelizhenden-mdb
approved these changes
Jun 18, 2026
yelizhenden-mdb
left a comment
yelizhenden-mdb
left a comment
Collaborator
There was a problem hiding this comment.
Such a helpful skill! Thanks!
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
2 participants
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.
What
Adds a local workflow for previewing how a PR renders the IPA docs before merging — no hosted infrastructure.
scripts/preview-pr.sh— checks out a PR and starts the Docusaurus dev server (supports--port,--no-open,--install)./preview-pr <n>slash command + apreview-ipaClaude Code skill that wrap the script.CONTRIBUTING.md— a short "Reviewing a pull request locally" section.