---
updatedOn: '2026-01-22T15:48:50.608Z'
---

# Docs

Welcome to Neon docs! This folder contains the source code of the [Neon docs](/docs/).

## Basic information

1. Every single Markdown file in this folder will be turned into a docs page.
2. Folder and file names should follow kebab-case.
3. `slug` is generated based on the folder structure and file names inside this folder. In order to see page `slug`, you can [start](../../README.md#run-the-website) and build the project with `npm run build` command that will display all generated pages.
4. Page `path` is generated by combining [`DOCS_BASE_PATH`](../../src/constants/docs.js) and page `slug`.
5. 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:

1. `title` — title of the page (required)
2. `subTitle` — subtitle of the page.
3. `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.
4. `redirectFrom` — array of strings with paths to redirect from to the page, should start and end with a slash, e.g. `/docs/old-path/`
5. `isDraft` — flag that says the page is not ready yet. It won't appear in production but will appear in the development mode.
6. `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.
7. `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](./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:

```yaml
- 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:

```yaml
  ...
  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`.

```diff
+- 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`.

```diff
  ...
  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.

```diff
  ...
  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 (e.g., "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](https://shiki.matsu.io/languages).

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

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

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

  - Multiple lines

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

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

  - Range of code lines

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

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

- use `[!code highlight]` to highlight a line.

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

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

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

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

  ```ts
  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:

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

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

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

  Example:

  ````md
  ```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:

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

  You can combine it with line highlighting and other flags:

  ````md
  ```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:

````md
<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>
````

<details>
<summary>Examples</summary>

![Code tabs example](images/code-tabs-example.jpg)

</details>

## External Code

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

### Usage

```markdown
<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              |

### Examples

```markdown
<ExternalCode
  url="https://raw.githubusercontent.com/neondatabase-labs/ai-rules/main/neon-auth.mdc"
  language="markdown"
  shouldWrap
  showLineNumbers
/>
```

### Best Practices

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

## Tabs

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

````md
<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:

```md
<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>
```

<details>
<summary>Examples</summary>

![Admonition example](images/admonition-example.jpg)

</details>

## CTA

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

```md
<CTA />
```

Check the example for default data of CTA block

<details>
<summary>Example</summary>

![CTA example](images/cta-example.jpg)

</details>

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

```md
<CTA title="Try it on Neon!" description="Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL Editor. Sign up for a free account to get started." buttonText="Sign Up" buttonUrl="https://console.neon.tech/signup" />
```

## Steps

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

```md
<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>
```

<details>
<summary>Example</summary>

![Steps example](images/steps-example.jpg)

</details>

## 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 [Neon Auth with Next.js](https://neon.com/docs/auth/quick-start/nextjs) and [Neon Auth & Data API TypeScript SDKs](https://neon.com/docs/reference/javascript-sdk) for usage examples.

````md
<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

<details>
<summary>Examples</summary>

![Two Column Layout example](images/two-column-layout-example.jpg)

Example with steps:

![Two Column Layout example](images/two-column-layout-steps-example.jpg)

</details>

## Feature List

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

```md
<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`.

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

<details>
<summary>Example</summary>

![Feature List example](images/feature-list-example.jpg)

</details>

## Checklist

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

```md
<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.

<details>
<summary>Example</summary>

![Checklist example](images/checklist-example.jpg)

</details>

## 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:

```md
├── 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`:

```md
![Neon 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:

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

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](https://www.markdownguide.org/extended-syntax/#definition-lists). Fully [WCAG-compliant](https://www.w3.org/TR/WCAG20-TECHS/H40.html). 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](https://github.com/neondatabase/website/pull/231/commits/8f795eaf700c31794a2267fc5978c22bfc649a0c):

```md
[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)

<details>
<summary>Examples</summary>

![Definition list example](images/definition-list-example.jpg)

</details>

## 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.

```md
<DetailIconCards>

<a href="https://api-docs.neon.tech/reference/getting-started-with-neon-api" description="Collaborate on open-source projects" icon="github">Headless vector search</a>

<a href="https://api-docs.neon.tech/reference/getting-started-with-neon-api" 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](https://github.com/neondatabase/website/blob/main/content/docs/shared-content/need-help.md) in folder `content/docs/shared-content/`, add to `sharedMdxComponents` the name of component and the path to component.

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

export default sharedMdxComponents;
```

Insert a shared markdown and render inline.

```md
## 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:

```md
<ComponentWithProps text="The pgvector extension" />
```

`component-with-props.md`

```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:**

```mdx
<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:

  ```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](../../README.md#getting-started) to see how changes look like before making a pull request.
