updatedOn	2026-08-26T16:06:50.814Z

Docs

Welcome to Neon docs! This folder contains the source code of the Neon docs.

Basic information

Every single Markdown file in this folder will be turned into a docs page.
Folder and file names should follow kebab-case.
slug is generated based on the folder structure and file names inside this folder. In order to see page slug, you can start and build the project with npm run build command that will display all generated pages.
Page path is generated by combining DOCS_BASE_PATH and page slug.
There is no need to add h1 to the page since it will be displayed automatically with the value from title field.

Fields

Right now Markdown files accept the following fields:

title — title of the page (required)
subTitle — subtitle of the page.
tag — tag for the page. It can be one of the following: new, beta, coming soon, deprecated, or you can use your own tag. Don't forget to add it to the navigation.yaml file as well.
redirectFrom — array of strings with paths to redirect from to the page, should start and end with a slash, for example /docs/old-path/
isDraft — flag that says the page is not ready yet. It won't appear in production but will appear in the development mode.
enableTableOfContents — flag that turns on the display of the outline for the page. The outline gets built out of second and third-level headings ([h2, h3]), thus appears as two-level nested max.
ogImage - the social preview image of the page.

⚠️ Please note that the project won't build if at least one of the Markdown files is missing a required field.

Navigation

Navigation data is stored in the navigation.yaml file.

Navigation Structure

The navigation system is a unified structure where:

Top-level items appear in the header navigation
Child items appear in the left sidebar

This creates a seamless navigation experience where users select a main category from the header and see its detailed structure in the sidebar.

Top Navigation Structure

Each top-level navigation item has the following structure:

- nav: Get started # Navigation label (displayed in header)
  slug: introduction # URL slug for the section
  title: Neon Docs # Page title
  icon: home # Icon identifier
  subnav: # Sub-navigation items for header dropdowns
    - title: Neon platform
      slug: manage/platform
      icon: settings
      items: # Sidebar navigation items
        ...

Important: Top-level items can contain either:

subnav: Sub-navigation items that appear as header dropdowns
items: Navigation items that appear in the sidebar

Sidebar Navigation Structure

The sidebar navigation supports multiple levels:

  ...
  items: # Sidebar navigation items
    - section: Features # Section header
      icon: features
      slug: guides/neon-features
      items: # Section items
        - title: Serverless
          slug: introduction/serverless
        - title: Autoscaling
          slug: introduction/autoscaling
          items: # Section subitems
            - title: Introduction
              slug: introduction/autoscaling
            - title: Architecture
              slug: introduction/autoscaling-architecture

How to add a new top navigation category

To add a new top-level navigation category, add a new item to the top level array with keys nav, slug, title, icon, and optionally items or subnav.

+- nav: New Category
+  slug: new-category
+  title: New Category Title
+  icon: new-icon
+  subnav:
+    ...

How to add a new section

To add a new section within a navigation category, add a new item with keys section, icon, and items.

  ...
  items:
+   - section: Architecture
+     icon: architecture
+     items:
+       ...

How to add a new page

To add a new page, add a new item with keys title and slug under the appropriate section or navigation level.

  ...
  items:
+   - title: Overview
+     slug: introduction/architecture-overview

Navigation Properties

nav: The label displayed in the top navigation header
slug: The URL path for the page/section
title: The display title for the page/section
icon: Icon identifier for visual representation
section: Section header for grouping related items
items: Array of navigation items
subnav: Sub-navigation items for the sidebar
tag: Optional tag (for example, "new", "beta") displayed next to the title

Important Notes

title in the sidebar may differ from title in the Markdown file
slug should always match the page's slug
The navigation supports unlimited nesting levels for complex documentation structures
Icons are referenced by name and should match available icon components
Tags like "new" or "beta" are automatically displayed with special styling

Code blocks

All available languages for code blocks can be found here.

You can use fenced code blocks with three backticks (```) on the lines before and after the code block. And display code with options

enable highlighting single lines, multiple lines, and ranges of code lines

Examples:

Single line highlight

```c++ {1}
#include <iostream>

int main() {
    std::cout << "Hello World";
    return 0;
}
```

Multiple lines

```c++ {1,2,5}
#include <iostream>

int main() {
    std::cout << "Hello World";
    return 0;
}
```

Range of code lines

```c++ {1-3,5}
#include <iostream>

int main() {
    std::cout << "Hello World";
    return 0;
}
```

use [!code highlight] to highlight a line.

export function foo() {
  console.log('Highlighted'); // [!code highlight]
}

use [!code word:xxx] to highlight a word.

export function foo() {
  // [!code word:Hello]
  const msg = 'Hello World';
  console.log(msg);
}

use [!code --] and [!code ++] to highlight a code diff.

export function foo() {
  const msg = 'Hello Word'; // [!code --]
  const msg = 'Hello World'; // [!code ++]
}

showLineNumbers - flag to show on the line numbers in the code block.

Example:

```c++ showLineNumbers
#include <iostream>

int main() {
    std::cout << "Hello World";
    return 0;
}
```

shouldWrap - flag to enable code wrapping in the code block.

Example:

```powershell shouldWrap
powershell -Command "Start-Process -FilePath powershell -Verb RunAs -ArgumentList '-NoProfile','-InputFormat None','-ExecutionPolicy Bypass','-Command ""iex (iwr -UseBasicParsing https://cli.configu.com/install.ps1)""'"
```

filename="..." - add a filename label above the code block.

Examples:

```jsx filename="src/App.jsx"
export default function App() {
  return <div>Hello</div>;
}
```

You can combine it with line highlighting and other flags:

```jsx filename="src/App.jsx" {2} showLineNumbers shouldWrap
export default function App() {
  return <div>Hello</div>;
}
```

Code Tabs

To display code tabs, wrap all pieces of code with <CodeTabs></CodeTabs> and write labels of code tabs in order:

<CodeTabs labels={["Shell", "C++", "C#", "Java"]}>

```bash {2-4}
#!/bin/bash
STR="Hello World!"
echo $STR
```

```c++
#include <iostream>

int main() {
    std::cout << "Hello World";
    return 0;
}
```

```csharp
namespace HelloWorld
{
    class Hello {
        static void Main(string[] args)
        {
            System.Console.WriteLine("Hello World");
        }
    }
}
```

```java
import java.io.*;

class GFG {
    public static void main (String[] args) {
       System.out.println("Hello World");
    }
}
```

</CodeTabs>

Examples

External Code

The ExternalCode component allows embedding code content from external sources with syntax highlighting.

Usage

<ExternalCode
  url="https://raw.githubusercontent.com/neondatabase/neon/main/README.md"
/>

Props

Prop	Type	Default	Description
url	string	(required)	URL to the raw file
language	string	(optional)	Language for syntax highlighting (defaults to file extension)
shouldWrap	boolean	false	Enables code wrapping in the code block
showLineNumbers	boolean	false	Shows line numbers in the code block
className	string	''	Additional CSS classes to apply to the component

Best Practices

Always use raw URLs from the GitHub repository (for example, https://raw.githubusercontent.com/...).
Use the language prop when the file extension doesn't match the actual content type.

Inline SVG

The InlineSvg component renders an SVG from public/ directly into the page DOM instead of through an <img> tag. Use it for diagrams with interactivity (CSS :hover states, SMIL begin="click" animations), which browsers ignore inside <img>-embedded SVGs. For static SVGs, prefer standard markdown image syntax, which adds zoom support.

Usage

<InlineSvg src="/docs/guides/my-diagram.svg" title="One-sentence description of the diagram for screen readers" />

Props

Prop	Type	Default	Description
src	string	(required)	Path to the `.svg` file, relative to `public/`
title	string	(optional)	Accessible label; sets `role="img"` and `aria-label` on the wrapper
className	string	(optional)	Additional CSS classes to apply to the wrapper

Best Practices

Keep SVGs script-free; <script> tags and inline event handlers are stripped at render time. Use CSS and SMIL for interactivity.
Use unique element ids inside each SVG (for example, marker ids). Inlined SVGs share the page's id namespace, so two SVGs on one page with the same id will conflict.
Always pass a title so the diagram is announced to screen readers.

Tabs

To display the tabs with content as image, video, code block, .etc, wrap the TabItem with Tabs

<Tabs labels={["Content", "CLI"]}>

<TabItem>
In your config v3 project, head to the `/metadata/databases/databases.yaml` file and add the database configuration as below.

```bash showLineNumbers
- name: <db_name>
  kind: postgres
  configuration:
    connection_info:
      database_url:
        from_env: <DB_URL_ENV_VAR>
    pool_settings:
      idle_timeout: 180
      max_connections: 50
      retries: 1
  tables: []
  functions: []
```

Apply the Metadata by running:

```bash
hasura metadata apply
```

If you've spun up the Hasura Engine with Docker, you can access the Hasura Console by accessing it in a browser at the URL of your Hasura Engine instance, usually http://localhost:8080.

<Admonition type="note">
To access the Hasura Console via the URL the HASURA_GRAPHQL_ENABLE_CONSOLE environment variable or the `--enable-console` flag must be set to true.
</Admonition>

</TabItem>

<TabItem>
Alternatively, you can create read replicas using the Neon API or Neon CLI.

```bash
curl --request POST \
     --url https://console.neon.tech/api/v2/projects/late-bar-27572981/endpoints \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $NEON_API_KEY" \
     --header 'Content-Type: application/json' \
     --data '
{
  "endpoint": {
    "type": "read_only",
    "branch_id": "br-young-fire-15282225"
  }
}
' | jq
```

</TabItem>

</Tabs>

Admonition

To improve the documentation readability, one can leverage an Admonition custom component. Just wrap your piece of text with <Admonition></Admonition> and pass the type.

There are 6 types of Admonition: note, important, tip, info, warning, comingSoon; the default is note.

You may also specify an optional title with prop title.

Example:

<Admonition type="note">
Highlights information that users should take into account, even when skimming.
</Admonition>

<Admonition type="important">
Crucial information necessary for users to succeed.
</Admonition>

<Admonition type="tip">
Optional information to help a user be more successful.
</Admonition>

<Admonition type="info">
Information that helps users understand the things better.
</Admonition>

<Admonition type="warning">
Critical content demanding immediate user attention due to potential risks.
</Admonition>

<Admonition type="comingSoon">
Information about features that are coming soon.
</Admonition>

Examples

Callout

A highlighted block for supplementary information the reader should notice but that doesn't fit the urgency of an Admonition. Use it for tips, best practices, or "good to know" context.

<Callout>

Your callout content here. Supports paragraphs, lists, and inline code.

</Callout>

To override the default label, pass a title prop:

<Callout title="Before you start">

Make sure you have Node.js 18+ installed.

</Callout>

Prop	Type	Default	Description
`children`	node	(required)	Content rendered inside the callout
`title`	string	`Good to know`	Label displayed in the header

When to use Callout vs Admonition

Callout — supplementary context, best practices, or neutral "good to know" information.
Admonition — warnings, important notices, tips with urgency, or coming-soon flags. Use when the information could cause user error if missed.

CTA

This is a simple block with title, description text and one CTA button that accomplish certain actions.

<CTA />

Check the example for default data of CTA block

Example

To change text in CTA block, you can pass to the component props title, description, buttonText, buttonUrl:

<CTA title="Try it on Neon!" description="Neon is the backend for apps and agents. Sign up for a free Neon account to start building." buttonText="Sign Up" buttonUrl="https://console.neon.tech/signup" />

Steps

To display numbered steps, wrap the content with Steps component.
Steps will be split by h2 headings.

<Steps>

## Step 1: Create the Initial Schema

First, create a new database called `people` on the `main` branch and add some sample data to it.

## Step 2: Create a development branch

Create a new development branch off of `main`. This branch will be an exact, isolated copy of `main`.

</Steps>

Example

Sticky Table

Use StickyTable for large markdown tables where readers need the header to remain visible while scrolling through the table. Regular markdown tables already get the default docs table styling; only wrap tables that need this sticky header behavior.

<StickyTable>

| Extension | PG14 | PG15 | Notes |
| --------- | ---: | ---: | ----- |
| pgvector  |  0.8 |  0.8 | Vector search support |
| postgis   |  3.3 |  3.5 | Geospatial support |

</StickyTable>

Notes

Use StickyTable only around a single markdown table.
Keep the table in markdown so it remains easy to edit in one place.
The component preserves the normal horizontal table scroll and adds a floating header for long tables.
Pass className to StickyTable to apply classes to the underlying table, for example <StickyTable className="min-w-[900px]">.

Two Column Layout

The TwoColumnLayout component creates a two-column layout for tutorial pages and reference documentation. Use TwoColumnLayout.Step for numbered tutorial steps or TwoColumnLayout.Item for default items. Nested content blocks should be wrapped with TwoColumnLayout.Block.

Note: Pages using TwoColumnLayout should include layout: wide prop to hide the right sidebar (Table of Contents) and provide more space for the two-column layout.

Check Managed Better Auth with Next.js and Neon TypeScript SDK for usage examples.

<TwoColumnLayout>

<TwoColumnLayout.Step title="Install dependencies">
<TwoColumnLayout.Block>

Install the required packages for your project.

</TwoColumnLayout.Block>
<TwoColumnLayout.Block label="Terminal">

```bash
npm install @neondatabase/neon-js
```

</TwoColumnLayout.Block>
</TwoColumnLayout.Step>

<TwoColumnLayout.Item title="Sign in with email" method="auth.signIn.email()" id="signin-email">
<TwoColumnLayout.Block>

Authenticate a user with their email and password.

</TwoColumnLayout.Block>
<TwoColumnLayout.Block>

```typescript
await client.auth.signIn.email({
  email: 'user@example.com',
  password: 'password123',
});
```

</TwoColumnLayout.Block>
</TwoColumnLayout.Item>

<TwoColumnLayout.Footer>
<Admonition type="note">
Additional information that spans both columns
</Admonition>
</TwoColumnLayout.Footer>

</TwoColumnLayout>

Components:

TwoColumnLayout.Step - Numbered step with title prop (for tutorials)
TwoColumnLayout.Item - Default item with title, method, and id prop
TwoColumnLayout.Block - Nested content block with optional label prop
TwoColumnLayout.Footer - Full-width content at the bottom of a step

Examples

Example with steps:

Feature List

To display a list of features, use the FeatureList component. Features will be split by h2 and h3 headings.

<FeatureList>

### Agent creates an app

A vibe coder imagines an app. Your agent builds it, full-stack.

### Gets a working database instantly, with no friction

Neon provisions the database behind the scenes via API.

</FeatureList>

You can pass icons prop to the FeatureList component to display icons for each feature.

List of available icons (extendable): src/components/shared/feature-list/icon/icon.jsx.

<FeatureList icons={['agent', 'speedometer']}>

Example

Checklist

To display a checklist, use the CheckList component with CheckItem items inside.

<CheckList title="Checklist title">

<CheckItem title="Check item 1" href="#check-item-1">
  Check item 1 description
</CheckItem>

<CheckItem title="Check item 2" href="#check-item-2">
  Check item 2 description
</CheckItem>

</CheckList>

Notes

Checklist options saved in the browser local storage.
Checklists with the same title will use the same local storage between pages.
If you don't pass title, the id will be generated from the page slug.
The best practice is to use CheckList with the Steps component on the page.

Example

Images

The images should be sourced in public/docs directory and be used in .md with the relative path, that begins with a / slash

Example file structure:

├── public
│ ├── docs
│ │ ├── conceptual-guides
│ │ ├── neon_architecture_2.png // put images in a directory with the same name as the .md file
├── content
│ ├── docs
│ │ ├── conceptual-guides
│ │ ├── architecture-overview.md

To display images using Markdown syntax, use the following syntax: ![alt text](image url). Example content in architecture-overview.md:

![lakebase architecture diagram](/docs/conceptual-guides/neon_architecture_2.png)

If you need an image without border to show an annotated piece of UI, use the "no-border" attribute as in the example below:

![lakebase architecture diagram](/docs/conceptual-guides/neon_architecture_2.png 'no-border')

Pages under content/pages/ round the corners of every image. If the artwork runs edge to edge and the rounding shaves off something you need to keep, opt that image out with the "square" attribute:

![agent setup in a code editor](/use-cases/full-stack-apps/neon-init.jpg 'square')

Images load lazily by default. For the one image that sits above the fold at the top of a page, add "priority" so it loads eagerly instead of waiting:

![agent setup in a code editor](/use-cases/full-stack-apps/neon-init.jpg 'priority')

Flags can be combined, separated by a space: 'square priority'. Use priority only for a hero image, never for images further down the page.

With this approach, all images on your doc pages will be displayed both on the production and GitHub preview.

Definition list

Custom mdx component that makes possible using extended markdown syntax for descriptions lists. Fully WCAG-compliant. It provides an accessible way to make term lists, and it's a generally good way to add structure to a text when a writer needs more than bullets and less than headings.

The usage is pretty straightforward:

[comment]: <> (other content here)

<DefinitionList>
[comment]: <> (required new line)
Scenario executor
: First definition
: Second definition

Soak test
: First and only definition

Smoke test
Another term for smoke test
: First definition for both terms
: Second definition for both terms
: ...n definition for both terms

[Stress test](/)
: First and **only** definition for both terms with additional markup <br/> Read more: [link](/)

[comment]: <> (other content here)
</DefinitionList>

[comment]: <> (other content here)

Acceptable markup for term

*italic*
[link](/)
**strong** - but that doesn't make sense, by default terms appearance is already bold
inlineCode - but it doesn't alter it's change in this context

Constraints

using emojis in dt is prohibited, as it potentially can mess up with id attribute, and href at anchor. We can not be sure which range will be used to display a particular symbol (depends on editor OS) and if it is going to be stripped.
if there are multiple terms for a given set of descriptions, only the first one will have an id and an anchor
make absolutely sure your dt text content is unique across the page to avoid id collisions

Acceptable markup for description

everything for term
emojis
any inline html
line breaks <br/> (recommended way to separate visually something inside a single description)

Examples

FAQ

Use the Faq component with FaqItem items to add a frequently-asked-questions section at the end of a page. This is the standard component for FAQs across docs and guides. Prefer it over ad-hoc ### question headings, bold **Q:/A:** text, or DefinitionList so every FAQ looks and behaves the same.

The component is built for SEO. It emits FAQPage schema.org JSON-LD structured data to help search engines and AI agents parse the questions and answers, and it renders each answer with native <details>/<summary> so the answer text stays in the DOM even when collapsed, keeping it crawlable and accessible. It also gives every FAQ consistent styling and deep-link anchors.

Add a ## Frequently asked questions heading above the component so the section shows up in the table of contents, then wrap the questions:

## Frequently asked questions

<Faq>

<FaqItem question="Why must I poll operations after restore?">
With `finalize_restore: true`, Neon moves compute resources to the new state. Until operations complete, connections still point to the old compute.
</FaqItem>

<FaqItem question="What if we need multiple preview environments?">
Restore different snapshots to new branches. Each restore creates a new branch with its own connection string.
</FaqItem>

</Faq>

Props

FaqItem:

question (required) — the question text. Rendered as an <h3> inside the <summary>, and used verbatim as the name in the JSON-LD.
id (optional) — anchor id for the item. Defaults to a slug generated from question, so #your-question-text deep links work without setting it.
defaultOpen (optional) — set to true to render the item expanded on load.

Notes

Answers accept full markdown: paragraphs, lists, tables, links, images, and code. Keep a blank line above and below block content inside FaqItem so MDX parses it.
Each question becomes an <h3> inside the component but does not appear in the table of contents (the TOC is built from markdown headings, not rendered JSX). The single ## Frequently asked questions heading is the TOC entry.
Put shared blocks like <NeedHelp/> after </Faq>, not inside a FaqItem.

Detail Icon Cards

DetailIconCards is a custom MDX component that displays data in a card format. Each card contains icon, title, href and description. This layout is especially useful for presenting grouped information in a visually pleasing and easy-to-understand way.

<DetailIconCards>

<a href="/docs/reference/api/get-started" description="Collaborate on open-source projects" icon="github">Headless vector search</a>

<a href="/docs/reference/api/get-started" description="Collaborate on open-source projects" icon="github">Open AI completions</a>

</DetailIconCards>

List of available icons in folder: /website/src/components/pages/doc/detail-icon-cards/images

Shared MDX components

Create a markdown file in folder content/docs/shared-content/, add to sharedMdxComponents the name of component and the path to component.

const sharedMdxComponents = {
  // ConponentName: 'shared-content/component-filename'
  NeedHelp: 'shared-content/need-help',
};

export default sharedMdxComponents;

Insert a shared markdown and render inline.

## Resources

- [Open AI tiktoken source code on GitHub](https://github.com/openai/tiktoken)
- [pg_tiktoken source code on GitHub](https://github.com/kelvich/pg_tiktoken)

<NeedHelp/>

You can pass props to the shared component:

<ComponentWithProps text="The pgvector extension" />

component-with-props.md

<Admonition type="note" title="Test component with props">
  {text}
</Admonition>

CopyPrompt

A reusable MDX component that shows a "copy prompt" box and lets users copy curated llm prompts from a file with one click.

Usage:

<CopyPrompt
  src="/prompts/serverless-driver-prompt.md"
  displayText="Use this pre-built prompt to get started faster."
  buttonText="Copy prompt"
/>

src prop is mandatory. displayText and buttonText are optional, if you want to override the defaults.

Prop	Type	Default	Description
`src`	string	(required)	Path to the markdown file or prompt content to copy
`displayText`	string	"Use this pre-built prompt to get started faster."	CTA text shown on the left
`buttonText`	string	"Copy prompt"	Button label

Where to place prompt files

Prompt markdown files should be placed in the public/prompts/ directory of your project. This allows them to be fetched at runtime by the CopyPrompt component using a path like /prompts/your-prompt-file.md.

Example:

Place your prompt file at: public/prompts/serverless-driver-guardrail-prompt.md

Reference it in your MDX:

<CopyPrompt src="/prompts/serverless-driver-guardrail-prompt.md" />

Contributing

For small changes and spelling fixes, we recommend using the GitHub UI because Markdown files are relatively easy to edit.

For larger contributions, consider running the project locally to see how changes look like before making a pull request.

Uh oh!

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Docs

Basic information

Fields

Navigation

Navigation Structure

Top Navigation Structure

Sidebar Navigation Structure

How to add a new top navigation category

How to add a new section

How to add a new page

Navigation Properties

Important Notes

Code blocks

Code Tabs

External Code

Usage

Props

Best Practices

Inline SVG

Usage

Props

Best Practices

Tabs

Admonition

Callout

When to use Callout vs Admonition

CTA

Steps

Sticky Table

Notes

Two Column Layout

Feature List

Checklist

Notes

Images

Definition list

Acceptable markup for term

Constraints

Acceptable markup for description

FAQ

Props

Notes

Detail Icon Cards

Shared MDX components

CopyPrompt

Where to place prompt files

Contributing