Docs site: publish the repo's Markdown to GitHub Pages

[mmcky]

Implements #9. The docs had grown into a real set — three guides, two plugin guides, the evaluation framework, the audit doctrine — readable only as GitHub blob pages. This renders them as a navigable site at quantecon.github.io/skills, built with mystmd and deployed by Actions.

Nothing moves

myst.yml points at every file where it already lives, including the ones inside plugin directories. There are no copies to keep in sync, the repo view and the site render from one source, and an installed plugin keeps shipping the documentation it needs — which is what the self-contained-plugin convention requires.

The cost of that choice is real and worth stating: the sources have to stay plain, GitHub-readable Markdown. No MyST-only directives in files that people also read on GitHub. That is now written down in developing-skills.md rather than left for the next contributor to discover by breaking it.

What the site contains

Section	Pages
—	The repo README, as the landing page
Guides	Using the skills · Developing skills · Tutorial: run an evaluation by hand
Plugins	Benchmark guide + evaluation framework · Audit guide + doctrine, QuantEcon context, reporting
Project	Catalog · Future ideas

reviews/ stays in-repo and unpublished — those are working records, not documentation. The qe plugin has no guide of its own yet (there is no qe/README.md), so it is covered by the README and the catalog; writing one is a natural follow-up on #3.

CI

Every PR builds the site and runs a link check. Only main deploys, so a broken docs change cannot replace the live site. Deployment waits on both gates.

The link check runs over the Markdown sources, not the built HTML — the theme renders as a single-page app with no crawlable link graph, and the sources are what has to stay correct in both contexts anyway. It runs offline deliberately: several links point at private QuantEcon repos that answer 404 to an unauthenticated checker, and a job that cries wolf is a job everyone learns to ignore.

It immediately earned its place. Seven links in the 2026-07-21 design review were written repo-root-relative from a file inside reviews/, so they have never resolved on GitHub either; they are fixed here. All 113 relative links in the repo now resolve.

Two known limitations

Both cosmetic, and neither worth the content rewrite that #9 explicitly rules out:

1. The plugin guides land at /readme and /readme-1. mystmd derives slugs from filenames and silently ignores a slug: key in the TOC (verified — it warns "extra key ignored"). The fix would be YAML frontmatter in each README, which GitHub renders as a table at the top of the file. Ugly URLs beat a table wedged above every plugin's documentation. Navigation labels are set correctly via title:, so only the URL is affected.
2. Four deep links into doctrine.md reach the right page without jumping to the section. GitHub emits #3-read-only-boundary for a numbered heading; mystmd emits #id-3-read-only-boundary. Making them agree means renumbering the doctrine headings, which would regress the GitHub view — the primary context, since that is where the agent and most readers read these files.

Before this can deploy

GitHub Pages is not enabled on this repo (has_pages: false). After merge, set Settings → Pages → Source to GitHub Actions. The deploy job will fail until that is done. I did not enable it myself — it is a repository setting that makes a new public surface live, so it should be your call rather than a side effect of a PR.

Verified locally with mystmd 1.10.1: builds clean at exit 0, all 12 pages render, and BASE_URL=/skills correctly rewrites asset and nav URLs for the project subpath.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a MyST (mystmd) documentation site configuration and CI workflow to build/link-check the repo’s Markdown and deploy it to GitHub Pages on pushes to main, keeping all content in its existing locations (single-source-of-truth).

Changes:

• Introduces myst.yml to render an explicit TOC spanning repo docs plus plugin docs in-place.
• Adds a GitHub Actions workflow to build the site, run an offline relative-link check, and deploy to Pages on main only.
• Updates existing Markdown to point readers to the published docs site and fixes review-doc relative links.

Reviewed changes

Copilot reviewed 5 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
myst.yml	Defines the MyST site project metadata and explicit TOC pointing at existing Markdown files in-place.
.github/workflows/docs.yml	Adds CI build + offline link check for PRs and deploy-to-Pages on main.
docs/developing-skills.md	Documents the docs site and how to preview it locally with mystmd.
README.md	Adds a prominent link to the published documentation site.
reviews/benchmark-design-2026-07-21-independent.md	Fixes relative links so they resolve from within reviews/.
.gitignore	Ignores MyST build output and Node dependencies created by local site builds.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.