Documentation Contribution Guide
Learn how to contribute to the Neon documentation
This page provides guidelines for contributing to the Neon documentation. Our goal is to create an environment where our community has the information and knowledge required to confidently participate in improving the Neon documentation.
TL;DR: Contributing to the Neon Docs
- You can edit files on GitHub via the Edit this page link on our documentation pages or by forking the neondatabase/website repository and submitting a pull request.
- If you want to contribute a guide, we provide a template to help you get started. See How to contribute for details.
- Reference this contribution guide as needed for Markdown and style guidelines.
Why should you contribute?
Open-source projects are always evolving. Contributing to documentation is a great way for beginners to get started in open source and for experienced developers to explain complex topics while sharing their knowledge with the community.
By contributing to the Neon docs, you're helping us create a stronger learning resource for all developers. Whether you've found a typo, a section that's hard to understand, or you've noticed that a certain topic is missing, your contribution is always welcome and appreciated.
How to contribute
Documentation source files are located in the neondatabase/website repository, in the /content/docs
directory. To contribute, you have two options:
- Edit files directly on GitHub.
- Fork the neondatabase/website repository, create a branch for your changes, and submit a pull request.
If you prefer the first option, which is great for edits and small updates, there is an Edit this page link at the bottom of each Neon documentation page.
Clicking the link takes you to the Markdown file in GitHub, where you can click the Edit this page icon to make a change. When you finish editing, commit your changes to create a pull request.
If you would rather fork the neondatabase/website repository and submit a pull request, but you're not familiar with the process, we suggest going through the GitHub Open Source Guide. This guide describes how to fork a repository, create a branch, and submit a pull request. To help you get started, we provide a GUIDE_TEMPLATE.md file, which you can find in the neondatabase/website repository, under the /content/docs/guides
directory. After you create a branch, copy the template file and rename it. Don't forget to add your guide to the sidebar. See Add a new page.
Markdown
Neon uses Markdown as the documentation source format. Markdown is a lightweight markup language that lets you add formatting elements to plaintext text documents. It's designed to be easy to read and easy to write.
If you're new to Markdown, GitHub provides an excellent guide to get you started. The GitHub Markdown Documentation covers most of the basic writing and formatting syntax you'll need to contribute to the Neon docs.
Preview changes in VSCode
At Neon, we use VSCode for writing documentation. VSCode includes a built-in markdown previewer that you can use to view your changes locally.
To use this feature, open the command palette (⌘ + ⇧ + V on Mac or Ctrl + Shift + V on Windows). This opens a preview window for viewing your changes in formatted Markdown.
Contribution review process
After you submit a contribution, the Neon documentation team reviews your changes, provides feedback, and merges the pull request when it's ready.
Please reach out to us on our Discord Server if you have any questions or need further assistance.
Documentation file structure
The Neon documentation file structure reflects the navigation you see on the website. However, the order of the directories under /content/docs/
is alphabetical.
- Every Markdown file in the
/docs
folder becomes a documentation page unless it's defined with anisDraft: true
property in the page frontmatter. - Folder and file names should use kebab-case (hyphens between words).
Documentation table of contents
This section describes how to modify the documentation table of contents, also referred to as the "sidebar". Adding, removing, or moving a page in the documentation requires updating the sidebar. The sidebar is defined in a yaml
file, conveniently named sidebar.yaml
, which you can find at the root of the /docs
directory.
Add a new category
To add a new category to the sidebar, add a new item to the top-level array with title
and items
key values, as shown below:
Add a new page
To add new page, add a new item to the items
array with the title
and slug
keys under the category or subcategory.
- The
title
in the sidebar may differ fromtitle
in the Markdown file. For example, your sidebar title might be a shorter version of the title in your Markdown file. This lets you write longer, more informative page titles while keeping the sidebar titles short, readable, and easy to scan. These titles should remain logically related. For example, in our docs we reduce the page title "Use Grafbase Edge Resolvers with Neon" to just "Grafbase" in the sidebar. slug
should always exactly match the page's slug (the last part of the URL after the final backslash "/", in our case the name of the Markdown file).
Markdown frontmatter
Each Neon documentation Markdown file includes a frontmatter section at the beginning of the file containing file metadata. The frontmatter section is distinguished by three dashes, as shown here:
The only required attribute is title
, which becomes the page title that appears on the page and the browser tab.
Frontmatter attributes
Frontmatter attributes include:
Attribute | Description |
---|---|
subtitle | A secondary title or description that appears on the page, under the main title. |
enableTableOfContents | A boolean flag (i.e., true or false) that tells the static site generator whether or not to generate a right-hand table of contents for the page. We recommend adding this option if your page has more than a few sections. |
isDraft | Adding this attribute and setting it to true prevents the page from becoming a documentation page and being searchable. Include this option to avoid publishing the content before its ready. |
redirectFrom | A list of directory paths that should redirect to this file. This is useful if the page has moved and you want old URLs to continue working. |
updatedOn | This attribute is added automatically. You do not need to add it. |
Example:
Heading levels
The page title in the frontmatter is translated into an h1
element when the page is converted to HTML.
Top-level section headings in the body of your document are defined with two hash characters, which is equivalent to an h2
heading:
To add a subsection heading, equivalent to an h3
, add another #
character:
- Try to avoid heading levels beyond h4 (
####
). - Do not skip a level, e.g., do not go from
##
to####
. - Ensure there's a blank line before and after each heading.
Common markup
Comment tags
To comment out content in a markdown file use this construction:
If you need to comment out more complicated blocks of code you can use JSX-style comments:
Unfortunately, JSX-style comments have problems with Prettier, so in case of using them you should add your file to .prettierignore.
Code blocks
To insert a code block into your Markdown file, specify three backticks (```) on the lines before and after the code. Specify the language identifier to enable code highlighting, as in this example:
You can add language-specific highlighting to code blocks, as in the example above. See Supported language highlighting for code blocks.
Code block accepts the following options:
showLineNumbers
: Shows the line numbers in the code blockshouldWrap
: Enables code wrapping in the code block. This is useful for long commands or connection strings that would otherwise require the reader to scroll.
Example:
Code tabs
To display code tabs, enclose all pieces of code within <CodeTabs></CodeTabs>
and specify labels in order, as shown in the following example:
To view this example in the Neon documentation, see Create a Next.js project and add dependencies.
Admonitions
The Neon documentation supports the following admonitions:
- Note
- Important
- Tip
- Warning
- Info
To use an admonition, enclose your text with <Admonition></Admonition>
and specify the admonition type: note
, important
, tip
, warning
, and info
. The default is note
.
You can specify a title with the title
property.
Example output:
Very important note
This is a very important note.
Diagrams and screen captures
Neon uses Figma to create diagrams.
If you're interested in updating or adding a diagram, please open a GitHub issue with your suggestions. Please include a draft, if possible. You can use a tool like tldraw to create a draft.
If possible, please take screen captures on a high resolution monitor (UHD/4K). Screen captures should be unaltered (no borders or special effects).
Diagrams and images are stored in the /public/docs
directory in the Neon website repository. The directory location of the diagram or image under public
mirrors the location of the file that includes the diagram or image, as shown below:
Example file structure:
To add an image to your Markdown file, add an entry that looks like this:
Style Guide
This section outlines the stylistic elements that we do our best to follow in the Neon documentation.
Voice and language
The voice in the documentation should sound like one human being explaining something to another, while striking the right balance between being approachable and professional.
Guidelines
-
Use contractions:
- Do: Use contractions like "it's", "don't", "you're" to make the tone more conversational.
- Example: "It's essential to save your progress."
- Don't: Overuse contractions, which can compromise clarity.
- Do: Use contractions like "it's", "don't", "you're" to make the tone more conversational.
-
Simplicity over jargon:
- Do: Choose simpler words when possible.
- Example: "Use the tool," not "Utilize the instrument."
- Don't: Oversimplify to the point of being inaccurate or leaving out useful context.
- Do: Choose simpler words when possible.
-
Active voice:
- Do: Prefer active voice.
- Example: "The software converts the file."
- Don't: Over-rely on passive voice.
- Example: "The file is converted by the software."
- Do: Prefer active voice.
-
Brief sentences:
- Do: Keep sentences concise.
- Example: "Check the settings."
- Do: Keep sentences concise.
-
Personalize when relevant:
- Do: Use "you" to address the reader.
- Example: "You can adjust the setting."
- Don't: Overdo direct addresses. Not every sentence should start with "You".
- Do: Use "you" to address the reader.
-
Consistent terminology:
- Do: Stick to one term for one concept.
- Example: Always use "dashboard". Don't mix that term with "control panel".
- Don't: Confuse with synonyms.
- Example: Switching between "log-in", "sign-in", and "access point".
- Do: Stick to one term for one concept.
-
Examples for clarity:
- Do: Provide clear examples.
- Example: "For instance, to upload a file, click on the 'Upload' button."
- Do: Provide clear examples.
-
Use US English:
- Do: Adhere to US English spelling and grammar rules.
-
Avoid emojis and exclamations:
- Don't: Use emojis or exclamation marks in the documentation.
Link instead of repeating text
Avoid repeating or duplicating information from other topics. Instead, link to the original source of information and explain why it is important.
Capitalization
Use lowercase wherever possible.
For topic titles, use sentence-style capitalization. For example: "Create your first project"
Product names should align with the official names of the products, protocols, etc., maintaining exact capitalization.
UI text
When referencing specific user interface text, such as button labels or menu items, use the same capitalization displayed in the user interface wherever possible.
Feature names
Generally, feature names should be lowercase.
Other terms
Capitalize names of:
- Neon plans. For example, "Neon Free Plan".
- Third-party organizations, software, and products. Kubernetes, Git, and Vercel.
- Methods or methodologies. Continuous Integration, Continuous Deployment, etc.
Follow the capitalization style used by the authoritative source, which may use non-standard case styles. For example: PostgreSQL, GitHub, npm.
Fake user information
When including user information in connection details, API calls, or UI instructions, don't use real user information or email addresses.
- Use an email address ending in
@example.com
ordomain.com
. - Use strings like
example_username
or one of the following diverse and non-gendered names: Zhang Kai, Alex Lopez, or Dana Smith.
Connection strings
Connection strings should be defined as follows:
If you need to provide a connection string with realistic values, use one of the user names mentioned above, AbC123dEf
for the password, and dbname
for the database name:
Commands, parameters, values, filenames
Commands, parameters, values, filenames, error messages, connection strings, and other similar items should be enclosed in backticks. For example:
-
"Run the
neon projects list
command." -
"Execute
git clone
to clone a Git repository..." -
git clone
is a command that should be in lowercase, whereas Git is the product and should have a capital G. -
"A connection string has this format:
postgresql://[user]:[password]@[neon_hostname]/[dbname]
"
Need help?
Join our Discord Server to ask questions or see what others are doing with Neon. Users on paid plans can open a support ticket from the console. For more detail, see Getting Support.