Closes DOCS-1057
Contributes to DOCS-1052
## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.
YES
## Problem
We have hundreds of MDX lint warnings in our docs going against style
best practices.
## Solution
Remove and replace in context the following:
- PostgreSQL. There was only one. There was concern about exceptions,
but I found none.
- Just
- Quickly
- Actually
### What changed
Edits follow the [Google developer documentation style
guide](https://developers.google.com/style): concise, direct, active
voice. The flagged words were removed when the sentence still read well,
or replaced when meaning needed to be preserved.
### Common patterns
| Flagged word | Approach | Example |
|---|---|---|
| **just** (filler) | Removed | "you just installed" → "you installed" |
| **just** (limiting) | **only** | "just one row" → "only one row" |
| **just like** | **like** / **the same as** | "function just like
regular users" → "function like regular users" |
| **not just** | **not only** | "not just errors" → "not only errors" |
| **quickly** (performance) | **efficiently** or removed | "find rows
quickly" → "find rows efficiently" |
| **quickly** (time) | **soon** / **rapidly** / removed | "expires too
quickly" → "expires too soon" |
| **actually** (filler) | Removed | "actually execute" → "execute"; "is
actually the most common" → "is the most common" |
## Tophatting
1. See the diff.
2. See that content continues to make sense in context.
3. Locally, `cd apps/docs` and run `pnpm run lint:mdx`.
4. Search for "just," "actually," "quickly", and "PostgreSQL" and see
there are 0 warnings.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Updated wording across quickstarts, guides, and troubleshooting
articles for grammar, clarity, and consistent step-by-step phrasing.
* Clarified key concepts including Row Level Security policy evaluation
across Supabase products, deferred foreign key constraint behavior, and
when `EXPLAIN ANALYZE` executes queries (and related side effects).
* Refined several troubleshooting instructions and added guidance to cap
log payload size to reduce billed Logs Ingest volume.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Nik Richers <nrichers@gmail.com>
Co-authored-by: Chris Chinchilla <chris.ward@supabase.io>
## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.
YES
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Improved AI, database, storage, and platform guides with clearer
explanations and more detailed workflow steps.
* Added descriptive captions and accessible alt text for multiple
diagrams and benchmark charts.
* Expanded MFA, connection, replication, partitioning, and integration
docs with clearer decision points and setup/login flow guidance.
* Clarified database schema and seed-data examples to better explain how
tables and relationships fit together.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Miranda Limonczenko <miranda.limonczenko@supabase.io>
## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.
YES
## What is this PR?
This PR makes some images easier to understand by AI tools.
Some are removed as they served minimal purposes. Some are replaced with
mermaid versions instead, which are more understandable by AI tools.
Next steps after this PR are to continue migrating harder images as well
as improving the text around images in general.
## Testing
```
pnpm install
pnpm dev --filter=docs # or: cd apps/docs && pnpm dev
```
Then visit each converted page and verify:
Diagrams render as Mermaid (not a broken image / raw code fence) in both
light and dark mode:
- /docs/guides/auth/auth-mfa/phone, /totp
- /docs/guides/database/connecting-to-postgres
- /docs/guides/platform/read-replicas (inside the accordion)
- /docs/guides/storage/schema/design
- /docs/guides/local-development/seeding-your-database
- /docs/guides/auth/signing-keys (image gone, prose + table intact)
Contributes to DOCS-1052
Contributes to DOCS-1057
## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.
YES
## What kind of change does this PR introduce?
Resolves linting warning for "let's" and adds an exception for product
name.
## Tophatting
1. Read the diff and see if changes make sense in context.
2. Run `pnpm lint:mdx`, search for "let's" and see no instances.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Updated instructional copy across multiple AI, authentication,
database, functions, realtime, storage, and troubleshooting guides to
improve clarity and consistency.
* Replaced conversational phrasing (for example, “Let’s…/Let’s see…”)
with direct imperatives, tightened example lead-ins, and adjusted a few
step explanations for readability.
* Refreshed some tutorial text and code-sample presentation in guides
(no behavioral changes).
* Added/adjusted minor MDX lint guidance in a couple of documents.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Nik Richers <nrichers@gmail.com>
*Summary*
- reorganize the navigation menu to highlight modules, consolidate API
security content, and move guide entries (auto-generated docs, type
generation, security topics) to the intended sections
- relocate the Data API hardening and custom claims RBAC guides into the
API subtree, updating internal references and redirects, and fixing
cross-links (including adjusting the Security reference order)
- adjust data API topic references (e.g., securing guide and role
management) to point to the new paths and ensure the helper link
ordering follows the requested layout
*Testing*
- Not run (not requested)
Change 1
<img width="1286" height="576" alt="image"
src="https://github.com/user-attachments/assets/d903e9b0-bbfc-403f-bcb9-eee540e466db"
/>
Change 2
<img width="1176" height="666" alt="image"
src="https://github.com/user-attachments/assets/82b3ea4c-b8d4-4cb9-ad90-6c39c8a1a997"
/>
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Reorganized API documentation structure, consolidating REST and
GraphQL API guides under a dedicated API section.
* Moved security-related guides to API documentation paths for better
organization.
* Implemented automatic redirects for old documentation links to new
locations.
* Updated navigation menu to reflect the restructured documentation
layout.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Chris Chinchilla <chris.ward@supabase.io>
Co-authored-by: Chris Chinchilla <chris@chrischinchilla.com>
The RLS description appeared to have been copy-pasted from elsewhere, and did not reflect the RLS rule.
Co-authored-by: Charis <26616127+charislam@users.noreply.github.com>
Miranda Limonczenko