dima/supabase

0 Fork 0

mirror of https://github.com/supabase/supabase.git synced 2026-10-05 09:25:06 +03:00

Files

T

Miranda Limonczenko 1608b16687 chore(docs) Direct contributors to the docs authoring skills (#50600 )

Prerequisite for
[DOCS-1289](https://linear.app/supabase/issue/DOCS-1289/get-the-linter-to-fix-what-it-flags-or-retirereplace-the-linter).

## Problem

The `write-the-docs` and `edit-the-docs` skills carry the docs style
guide, so a contributor who uses them writes to the guide without having
read it. Right now nothing points a contributor at them.
`apps/docs/CONTRIBUTING.md` describes the skills as an option for agent
users, halfway down a 559-line page, and no other contributor-facing
file mentions them at all.

## Solution

- **CodeRabbit reminder.** One path instruction for
`apps/docs/content/**/*.mdx`. When a page collects two or more style,
terminology, or structure issues, CodeRabbit adds a single comment
pointing the author at `/write-the-docs` or `/edit-the-docs`. A single
nit gets no pointer, so the comment reads as a signal rather than
boilerplate.
- **Docs CONTRIBUTING.** The intro lists the skills by task, draft
through self-review, before the style rules, and links the existing
skills section for framing and architecture. The section opener now
reads as an expectation rather than a conditional, with the agent
mechanics moved to a second paragraph.
- **Root CONTRIBUTING.** A pre-flight check under Pull Requests, with
the same task list nested under it. Matches the docs checklist item in
#50591.
- **Word list.** Names the skills that apply the list.
- **Docs README and DEVELOPERS.** One sentence in each Contributing
section.

**Not in this PR:** CodeRabbit reminds, it doesn't enforce. Feeding the
two `SKILL.md` files to `knowledge_base.code_guidelines` would make it
review docs content against the style guide. That's a decision for
DOCS-1289 itself.

**Verification caveat:** this PR changes no MDX under
`apps/docs/content/`, so the new path instruction doesn't fire on its
own review.

## Manual testing

1. See all new content references in the diff.
2. Review for clarity and value.
3. Consider suggesting other ways to promote the usage of this skill to
all docs contributors.

2026-09-21 10:07:21 -07:00

3.2 KiB

Raw 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 repo organization and style guide, 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.2 KiB Raw Blame History