Skip to content

feat: add support for colocated docs - #8816

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

joshblack wants to merge 10 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

🦋 Changeset detected

Latest commit: d21ce7b

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package
Name Type
@primer/react Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another 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
joshblack and others added 2 commits November 21, 2026 13:14
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 78117385-8e45-436f-974c-bb5f0d5553af
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 — d21ce7b0 Deployed Nov 21, 2026 by github-actions[bot]
github-pages — d21ce7b0 Deployed Nov 21, 2026 by joshblack via deploy-preview #34490
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