mirror of
https://github.com/supabase/supabase.git
synced 2026-10-06 01:45:10 +03:00
Miranda Limonczenko
a5688423d0
Closes DOCS-1320 Was the bottom of a two-PR stack. The commit from #50680 moved here, so that PR is closed and this one carries both changes. ## Problem The CLI getting started guide had accumulated structural and prose problems, none of which change what the page claims: - **Nine flat H2 headings**, with Beta channel and Updating the Supabase CLI sitting between installing and running. A first-time reader crossed about 150 lines of beta and upgrade tabs before reaching `supabase init`. - **The introduction opened with a two-step procedure under no heading**, listing `init` and `start` before the CLI is installed. Its first sentence named the tool and where it runs rather than what the reader gets. - **Running a local Supabase project ran concept, fact, procedure, and process together** as one stretch of prose, so the two commands the reader has to run sat in paragraphs between the Docker background and the first-run note. - **Task headings mixed gerunds with imperatives:** Installing, Running, Stopping, and Updating next to Access and Manage. - **No navigation.** A long guide that mixes information types opened straight into commands, with no outline of its major groups. The sidebar contents is not a substitute: it isn't part of the document, and the generated markdown an agent reads has no sidebar at all. - **Four more sequences were prose.** Installing via npm, installing a Linux package, the pre-upgrade backup, and opting out of telemetry each had to be followed in order with nothing marking the order. - **Smaller things:** the Studio screenshot's alt text named the topic its heading already states, two links used "note above" and "here" as their text, and an admonition restated where `sb_publishable_...` comes from. ## Solution Twelve commits, one change type each, plus a master merge and its fixup. - **Style.** The install-method callout drops from four blocks to two paragraphs and uses the documented `title` prop. Active voice on the Postgres, analytics, and telemetry instructions. Descriptive link text. Alt text that describes the Studio screenshot rather than naming it. Cut the admonition restating `sb_publishable_...`. - **Structure.** Beta channel and Updating the Supabase CLI move out of the getting started path. - **Grouping.** Local setup goes under Set up a local project, updating and beta builds under Change your CLI version. The intro's `init` and `start` list gets a Quickstart heading. - **Value statement.** The opening sentence now says what the reader gets. - **Procedure format.** Running a local Supabase project leads with the container runtime prerequisite, then four numbered actions, then the first-run download as an outcome. Starting the container runtime is its own step, since the old prose only assumed it with "with a container runtime running". - **Imperative headings.** Install, Run, Access, Stop, Update, Use the beta channel. - **Four more procedures.** npm install, Linux packages, the pre-upgrade backup, and telemetry opt-out. The three pre-upgrade commands were one unexplained block inside an admonition, so each step now says what its command does. Re-enabling telemetry moves to a sentence, since it's the reverse action rather than a step. - **Intro navigation** listing the major groups, each line saying what the reader gets from it. - **Connect to a hosted project** (from #50680). A new section between Stop local services and Change your CLI version, saying the stack runs only on the reader's machine and nothing reaches a hosted project until they sign in and link one, then pointing at the page that owns the procedure. No commands. The `init` step gains a sentence saying it creates local files only, and the value statement and intro navigation cover the added goal. - **Style guide and word list fixes** from an audit of the page against `CONTRIBUTING.md` and `WORD_LIST.md`. `directory` over `folder` in command-line contexts, `might` over `may`, present tense over `will`, a noun after `this`, no `above` as a pointer, concrete verbs over `manage`, no time-relative `latest`, no parentheses for supplementary information, and an impact-first `caution` on the pre-upgrade callout. The container runtime list becomes a table of tool and platforms, and the group heading becomes Change your CLI version. ## Preview links | Site | Live | Preview | Search for | | ---- | ---- | ------- | ---------- | | Docs | [/docs/guides/local-development/cli/getting-started](https://supabase.com/docs/guides/local-development/cli/getting-started) | [/docs/guides/local-development/cli/getting-started](https://docs-git-docs-cli-getting-started-edits-supabase.vercel.app/docs/guides/local-development/cli/getting-started) | Change your CLI version, Connect to a hosted project | ## Manual testing 1. Open the docs preview link above. 2. Read the introduction. It opens with a value statement, then links the four major groups. Under Quickstart, the install-method callout explains how the install method changes the command you run. 3. Read the On this page list. It nests: Quickstart, Set up a local project with four sections under it, Change your CLI version with two sections under it, Telemetry, Learn more. 4. Check Run a local Supabase project renders four numbered steps, with code blocks inside steps 3 and 4. Check the npm tab of Install the Supabase CLI renders three, and How to opt out renders two. 5. Load the page at `#installing-the-supabase-cli`, `#beta-channel`, and `#updating-the-supabase-cli`. All three land on their sections despite the renamed headings. 6. Load the legacy path `/docs/guides/cli/getting-started#updating-the-supabase-cli`. It redirects to the current path and keeps the fragment. 7. Check the introduction's group list includes Connect to a hosted project, and that the section appears in the On this page list between Stop local services and Change your CLI version. 8. Check that section is two sentences and a pointer, with no commands. 9. In Run a local Supabase project, select the "Connect to a hosted project" link in step 3. The page scrolls to that section. 10. Follow both outbound links from the new section and confirm they resolve, including the `#configure-github-actions` fragment. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Reorganized the local development guide with a clearer quickstart, setup steps, service access instructions, and CLI version guidance. * Expanded installation examples to include bun and clarified package-runner commands. * Clarified upgrade, backup, container cleanup, and telemetry instructions. * Added a reference to the Microsoft Writing Style Guide. <!-- end of auto-generated comment: release notes by coderabbit.ai -->