updatedOn
2024-10-09T23:54:43.681Z

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 sidebar.yaml file as well.
redirectFrom — array of strings with paths to redirect from to the page, should start and end with a slash, e.g. /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.

Sidebar

Sidebar data is stored in the sidebar.yaml file.

How to add a new category

In order to add a new category to the sidebar, add a new item to the top level array with keys title and items.

For example:

 - title: Category 1
   items:
     - title: Page 1
       slug: page-1
+- title: Category 2
+  items:
+    - title: Page 2
+      slug: page-2

How to add a new subcategory

In order to add a new subcategory, add a new item to items array with keys title and items under specific category.

For example:

 - title: Category 1
   items:
     - title: Page 1
       slug: page-1
 - title: Category 2
   items:
     - title: Page 2
       slug: page-2
+    - title: Subcategory 1
+      items:
+        - title: Page 3
+          slug: page-3

How to add a new page

In order to add a new page to the root level, add slug in the same level with title. You can add tag as well if your page is tagged.

 - title: Root page 1
   items:
     - title: Page 1
       slug: page-1
 - title: Root page 2
   items:
     - title: Page 2
       slug: page-2
+ - title: Root page 1
+   slug: root-page-1
+   tag: new
+   items:
+     - title: Page 1
+       slug: page-1
+       tag: coming soon
+ - title: Root page 2
+   slug: root-page-2
+   items:
+     - title: Page 2
+       slug: page-2

In order to add new page under Category, add a new item to items array with keys title and slug under specific category or subcategory:

For example:

 - title: Category 1
   items:
     - title: Page 1
       slug: page-1
 - title: Category 2
   items:
     - title: Page 2
       slug: page-2
    - title: Subcategory 1
      items:
        - title: Page 3
          slug: page-3
+       - title: Page 4
+         slug: page-4
+   - title: Page 5
+     slug: page-5

title in the sidebar may differ from title in Markdown file.
slug should always match page's slug.

How to add a single page to doc sidebar

To add a single page https://example.com/changelog to the docs sidebar, add the boolean isStandalone to the first level of the list

title in the sidebar may differ from title in Markdown file.
slug should always match page's slug.
isStandalone - the boolean for the single page in sidebar.

+- title: Changelog
+  slug: changelog
+  isStandalone: true
 - title: Category 1
   items:
     - title: Page 1
       slug: page-1
 - title: Category 2
   items:
     - title: Page 2
       slug: page-2
    - title: Subcategory 1
      items:
        - title: Page 3
          slug: page-3

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); // prints Hello World
}

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)""'"
```

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

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, warning, info, comingSoon; the default is note.

You may also specify an optional title with prop title.

Example:

<Admonition type="note" title="Your title">
  The branch creation process does not increase load on the originating project. You can create a branch at any time without worrying about downtime or performance degradation.
</Admonition>

<Admonition type="info">
  The branch creation process does not increase load on the originating project. You can create a branch at any time without worrying about downtime or performance degradation.
</Admonition>

Examples

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 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" />

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:

![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:

![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. 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

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="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 in folder content/docs/shared-content/, add to sharedMdxComponents the name of component and the path to component.

const sharedMdxComponents = {
  // name of component: path to component (not including content/docs/)
  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/>

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.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Docs

Basic information

Fields

Sidebar

How to add a new category

How to add a new subcategory

How to add a new page

How to add a single page to doc sidebar

Code blocks

Code Tabs

Tabs

Admonition

CTA

Images

Definition list

Acceptable markup for term

Constraints

Acceptable markup for description

Detail Icon Cards

Shared MDX components

Contributing

Files

README.md

Latest commit

History

README.md

File metadata and controls

Docs

Basic information

Fields

Sidebar

How to add a new category

How to add a new subcategory

How to add a new page

How to add a single page to doc sidebar

Code blocks

Code Tabs

Tabs

Admonition

CTA

Images

Definition list

Acceptable markup for term

Constraints

Acceptable markup for description

Detail Icon Cards

Shared MDX components

Contributing