supabase/apps/docs/DEVELOPERS.md

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.

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:

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

Types of documentation

https://supabase.com/docs has several different kinds of documentation, all coming from different sources.

Guides

The primary, instructional type of content. Basically anything that lives on the https://supabase.com/docs/guides route. This includes Guides for Auth, Database, Storage, Realtime, Edge Functions, as well as general resources, self-hosting instructions, and integrations. These are all .mdx files — a combination of Markdown and Javascript.

Things to know

Here's a simple example .mdx Guide, and here is the source on Github.

Some things to note:

1. The files need to import a Layout at the top
2. The files need to export a Page at the bottom with the <Layout> component
3. The files frontmatter is stored in const meta = {}. You should always include title and description.
4. You can write Markdown as you normally would, but you can also write regular Javascript and JSX. Note the examples array that we iterate over.
5. Any Javascript variables you use in these files need to be exported in order to be used (i.e., export const examples = []).

Using components

You can use any standard React components in these .mdx files without having to explicitly import them in each file. All components get imported in a common components file and can be used in any .mdx file. Components can also be "intercepted" and modified via this file. Note how we're intercepting the h2, h3 and code tags and modifying them before converting the mdx to html.

Reference docs for client libraries

We maintain client libraries for JavaScript and Flutter/Dart (with more to come). These reference docs document every object and method available for developers to use. They are assembled from different sources and work much differently than the .mdx Guides we just looked at.

The client libraries are essentially wrappers around the clients for the various tools we use — GoTrue, PostgREST, Storage, Functions, and Realtime. The easiest way to describe how the things fit together is to look at an example and trace where the various pieces of information are coming from.

Example

Let's look at the updateUser() function in the supabase-js library.

Common file

Several pieces of information for this function come from a common file where we store information shared by all libraries.

1. id — used to identify this function
2. title - the human-readable title
3. slug — the url slug
4. product - the Supabase tool or product that "owns" this function. Since updateUser() is an auth function, its product is auth
5. type — updateUser() is a function and marked as such, but we can also have sections of markdown interspersed with these function definitions.

When a new function is added, this info would need to be manually added to the common file.

Function Parameters

The updateUser() function takes one parameter: attributes. The details for this parameter live in the GoTrue client library, referenced via a $ref property in the supabase-js spec file. Here, the $ref property is pointing to the actual function definition in the gotrue-js library. The accepted values for the attributes parameter come from the type definition.

These individual library spec files are fetched via this Makefile, and get transformed to combine the information we need (params, types, etc). Unless you're a library maintainer, you shouldn't need to worry about this part of the process.

If you are a library maintainer, the last important note about these library files is that the Makefile pulls from the gh-pages branch of the client library repo. Here's an example of the realtime-js spec file. Updating something like function params or returns, the process is:

1. Get your changes merged to master in your library
2. This will kick off an action that automatically updates the spec file in the library's gh-pages branch
3. Run make in /spec of the supabase/supabase repo. This will regenerate all of the tsdoc files that the docs site uses
4. You should now see the changes you've made in the docs site locally

Function Examples

The updateUser() function has three examples listed with it. The examples are stored along with the $ref property in the supabase_js_v2 spec file.

Rendering in Next.JS

These reference docs are rendered by Next.JS via a dynamic route using a [...slug.tsx]. Here, we use the library spec file and the common file to output the info you see on the page.

Other reference docs

The reference docs for the Supabase Management API and the Supabase CLI are a little more straightforward than the client libraries. Both files also have a common file which handles things like title, id and slug. Both also have a spec file detailing things like parameters, descriptions, and responses (Management API / CLI)

On the Next.JS side of things, these work almost exactly the same as the client libaries with a dynamic [...slug.tsx].

Misc

Search

Search is handled using a Supabase instance. During CI, a script aggregates all content sources (eg. guides, reference docs, etc), indexes them using OpenAI embeddings, and stores them in a Supabase database.

At runtime, an Edge Function is executed that performs a similarity search between the user's query and the above content sources using pgvector embeddings.