Skip to content

feat: add support for colocated docs - #8816

Draft
joshblack wants to merge 8 commits into
mainfrom
feat/add-colocated-docs
Draft

joshblack wants to merge 8 commits into
mainfrom
feat/add-colocated-docs

Conversation

@joshblack

@joshblack joshblack commented Nov 21, 2026 •

Copy link
Copy Markdown
Member

Part of: #8807

Add support for colocated docs. The strategy for this is that:

  • We ship an agent skill, primer-react, that tells agents to look at @primer/react/docs/AGENTS.md
  • This file tells the agent about the layout of docs in the package
  • In this PR, we provide support for component props through dist/docs/components/{ComponentName}/props.md
  • This PR also includes support for importing and using metadata from docs entrypoints (to make it easier to consume in the website)

This PR includes the migration of our existing *.docs.json files over into *.docs.ts. All JSON files and component metadata stuff remains so there should be no risk to shipping this alongside what we have already.

Finally, this PR contains a skill for component docs reviews and an agentic workflow for (hopefully) keeping them in sync

Changelog

New

  • Add support for colocated docs through:
    • The docs/AGENTS.md path
    • Markdown files for props published to dist/docs/components/{ComponentName}/props.md
    • Entry points for component docs, including:
      • @primer/react/docs
      • @primer/react/docs/deprecated
      • @primer/react/docs/experimental
      • @primer/react/docs/next
  • Colocated docs are defined in *.docs.ts files by a defineComponent helper
  • The structure currently mirrors our *.docs.json files to help with migration

Changed

Removed

Rollout strategy

  • No rollout required

@changeset-bot

changeset-bot Bot commented Nov 21, 2026 •

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: 192a4ee

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@github-actions github-actions Bot added staff Author is a staff member integration-tests: recommended This change needs to be tested for breaking changes. See https://arc.net/l/quote/tdmpakpm labels Nov 21, 2026
@github-actions

Copy link
Copy Markdown
Contributor

⚠️ Action required

👋 Hi, this pull request contains changes to the source code that github/github-ui depends on. If you are GitHub staff, test these changes with github/github-ui using the integration workflow. Check the integration testing docs for step-by-step instructions. Or, apply the integration-tests: skipped manually label to skip these checks.

@joshblack joshblack changed the title Feat/add colocated docs feat: add support for colocated docs Nov 21, 2026
@github-actions
github-actions Bot temporarily deployed to storybook-preview-8816 November 21, 2026 02:54 Inactive
Check public component docs coverage and hand verified gaps from a daily scanner to a docs-only PR fixer.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 78117385-8e45-436f-974c-bb5f0d5553af

This branch was successfully deployed

2 active deployments
storybook-preview-8816 — 192a4ee2 Deployed Nov 21, 2026 by github-actions[bot]
github-pages — 192a4ee2 Deployed Nov 21, 2026 by joshblack via deploy-preview #34487
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

integration-tests: recommended This change needs to be tested for breaking changes. See https://arc.net/l/quote/tdmpakpm staff Author is a staff member

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant