dima/supabase

0 Fork 0

mirror of https://github.com/supabase/supabase.git synced 2026-10-05 17:35:10 +03:00

Files

T

Miranda Limonczenko 36371de151 docs: trim CONTRIBUTING to repo mechanics and point at the style guide (#50743 )

Part 3 of 3. Stack: #50742 → #50744 → #50743. Review #50742 and #50744
first.

Closes DOCS-1177

## Problem

`CONTRIBUTING.md` mixed how to write a page with how the repo is laid
out. That's why it reached 568 lines, and why a contributor looking for
either half reads past the other.

#50742 gives the writing half its own home.

## Solution

Trim `CONTRIBUTING.md` to repo mechanics, 568 lines down to 163.

**Removed**, now in the style guide: general principles, information
types, document types, components and elements, styling and grammar,
word usage.

**Kept**: the skills table, repo organization, guide and reference
structure, content reuse, search. Content listings keeps its data file,
ID rules, and test command here; the when-to-use-one part is in the
style guide.

**Added**: a table linking each style guide file.

Wire the contributor-facing entry points at the guide:

- `apps/docs/AGENTS.md` — gains a style guide section listing each file
separately, so an agent can load one file without the others. This
auto-loads for anything under `apps/docs`, making it the
highest-leverage pointer in the repo.
- Root `AGENTS.md` — claimed the skills are "the source of truth for
conventions." For docs content style that's now the guide, with the
skills as the process that applies it.
- `.github/pull_request_template.md`, `.coderabbit.yaml`,
`apps/docs/README.md`, `apps/docs/DEVELOPERS.md` — updated paths.

Drop the `.prettierignore` exemption for `apps/docs/CONTRIBUTING.md`.
It's short enough to format now, and a repo that publishes a style guide
shouldn't exempt its own contributing doc.

## Notes for review

Discoverability in a markdown-only guide is entirely these pointers, so
they're the load-bearing part of this PR rather than cleanup.

Both surviving anchor links into `CONTRIBUTING.md` target
`#ai-agent-skills-for-docs-authoring`, which is kept. No dangling
anchors.

This PR sits last in the stack on purpose. It deletes the style sections
that seven skill instructions referenced, so it has to land after #50744
rewires them.

## Manual testing

1. Open `apps/docs/CONTRIBUTING.md` and confirm every remaining section
is repo mechanics, and the style guide table links resolve.
2. Confirm `apps/docs/AGENTS.md` names each style guide file, in size
order: `WORD_LIST`, `01-voice-and-tone`, `02-elements`,
`03-page-structure`.
3. Run `grep -rn "apps/docs/WORD_LIST" --include="*.md"
--include="*.yaml" . | grep -v node_modules` and confirm only the
intentional stub matches.
4. Run `npx prettier --config prettier.config.mjs --check
apps/docs/CONTRIBUTING.md`.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Documentation**
* Updated contributor guidance to distinguish writing conventions from
repository mechanics, with the style guide as the reference for
documentation style.
* Added style guide links and clarified when to use the writing and
editing skills.
* Revised the docs contribution guide with a style guide file list and
steps for adding content listings.
* Updated the pull request checklist to direct contributors to the
documentation skills for style guidance.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

2026-09-25 20:22:47 -07:00

3.3 KiB

Raw Permalink Blame History

Developing Supabase Docs

Getting started

Thanks for your interest in Supabase docs and for wanting to contribute! Before you begin, read the code of conduct and check out the existing issues. This document describes how to set up your development environment to contribute to Supabase docs.

For a complete run-down on how all of our tools work together, see the main DEVELOPERS.md. That readme describes how to get set up locally in lots of detail, including minimum requirements, our Turborepo setup, installing packages, sharing components across projects, and more. This readme deals specifically with the docs site.

Tip

If you work at Supabase, branch this repo directly to make PRs. Don't use a fork. This lets the CI checks auto-run and speeds up review.

Local setup

supabase.com/docs is a Next.js site. You can get setup by following the same steps for all of our other Next.js projects:

Follow the steps outlined in the Local Development section of the main DEVELOPERS.md
If you work at Supabase, from apps/docs run pnpm run dev:secrets:pull to write internal env vars to .env.local. If you're a community member, create apps/docs/.env.local and add this line: NEXT_PUBLIC_IS_PLATFORM=false
Start the local docs site by navigating to /apps/docs and running pnpm run dev
Visit http://localhost:3001/docs in your browser - don't forget to append the /docs to the end
Your local site should look exactly like https://supabase.com/docs

AI friendly documentation

This project generates Markdown files for each page under /docs/guides/.. path.

To test locally, within the apps/docs directory:

Run pnpm build:guides-markdown
Run pnpm dev

This creates Markdown files for all routes under the public/markdown/guides directory, ignored by Git.

For production this setup runs as a prebuild task to allow Vercel to bundle these files with middleware and functions.

Accessibility checks

Docs pages are scanned for WCAG 2.1 A/AA issues with axe-core, as part of the Playwright suite in e2e/docs. Pull requests scan the pages your change affects, limited to the main article.

To scan the pages your current branch changes:

PLAYWRIGHT_BASE_URL=https://supabase.com pnpm e2e:docs:a11y

That resolves which pages to scan from your branch, but reads them from production, so it won't see your edits and will 404 on a page you just added. Point PLAYWRIGHT_BASE_URL at your pull request's preview to scan your own content.

See e2e/docs/README.md for coverage and skipped rules.

Contributing

For how to write a page, see the style guide. For repo organization, see the contributing guide. If you write with an AI coding agent, use the /write-the-docs skill to draft, /edit-the-docs to revise an existing page, and /review-the-docs to self-review before you open a PR.

3.3 KiB Raw Permalink Blame History