b4eff7020b
## Why? The Grammarly extension is no longer active. - https://github.com/znck/grammarly - Closes https://github.com/vercel/next.js/issues/66194
408 lines
18 KiB
Text
408 lines
18 KiB
Text
---
|
|
title: Docs Contribution Guide
|
|
nav_title: Contribution Guide
|
|
description: Learn how to contribute to Next.js Documentation
|
|
---
|
|
|
|
Welcome to the Next.js Docs Contribution Guide! We're excited to have you here.
|
|
|
|
This page provides instructions on how to edit the Next.js documentation. Our goal is to ensure that everyone in the community feels empowered to contribute and improve our docs.
|
|
|
|
## Why Contribute?
|
|
|
|
Open-source work is never done, and neither is documentation. Contributing to docs is a good way for beginners to get involved in open-source and for experienced developers to clarify more complex topics while sharing their knowledge with the community.
|
|
|
|
By contributing to the Next.js docs, you're helping us build a more robust learning resource for all developers. Whether you've found a typo, a confusing section, or you've realized that a particular topic is missing, your contributions are welcomed and appreciated.
|
|
|
|
## How to Contribute
|
|
|
|
The docs content can be found on the [Next.js repo](https://github.com/vercel/next.js/tree/canary/docs). To contribute, you can edit the files directly on GitHub or clone the repo and edit the files locally.
|
|
|
|
### GitHub Workflow
|
|
|
|
If you're new to GitHub, we recommend reading the [GitHub Open Source Guide](https://opensource.guide/how-to-contribute/#opening-a-pull-request) to learn how to fork a repository, create a branch, and submit a pull request.
|
|
|
|
> **Good to know**: The underlying docs code lives in a private codebase that is synced to the Next.js public repo. This means that you can't preview the docs locally. However, you'll see your changes on [nextjs.org](https://nextjs.org/docs) after merging a pull request.
|
|
|
|
### Writing MDX
|
|
|
|
The docs are written in [MDX](https://mdxjs.com/), a markdown format that supports JSX syntax. This allows us to embed React components in the docs. See the [GitHub Markdown Guide](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) for a quick overview of markdown syntax.
|
|
|
|
### VSCode
|
|
|
|
#### Previewing Changes Locally
|
|
|
|
VSCode has a built-in markdown previewer that you can use to see your edits locally. To enable the previewer for MDX files, you'll need to add a configuration option to your user settings.
|
|
|
|
Open the command palette (`⌘ + ⇧ + P` on Mac or `Ctrl + Shift + P` on Windows) and search from `Preferences: Open User Settings (JSON)`.
|
|
|
|
Then, add the following line to your `settings.json` file:
|
|
|
|
```json filename="settings.json"
|
|
{
|
|
"files.associations": {
|
|
"*.mdx": "markdown"
|
|
}
|
|
}
|
|
```
|
|
|
|
Next, open the command palette again, and search for `Markdown: Preview File` or `Markdown: Open Preview to the Side`. This will open a preview window where you can see your formatted changes.
|
|
|
|
#### Extensions
|
|
|
|
We also recommend the following extensions for VSCode users:
|
|
|
|
- [MDX](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx): Intellisense and syntax highlighting for MDX.
|
|
- [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode): Format MDX files on save.
|
|
|
|
### Review Process
|
|
|
|
Once you've submitted your contribution, the Next.js or Developer Experience teams will review your changes, provide feedback, and merge the pull request when it's ready.
|
|
|
|
Please let us know if you have any questions or need further assistance in your PR's comments. Thank you for contributing to the Next.js docs and being a part of our community!
|
|
|
|
> **Tip:** Run `pnpm prettier-fix` to run Prettier before submitting your PR.
|
|
|
|
## File Structure
|
|
|
|
The docs use **file-system routing**. Each folder and files inside [`/docs`](https://github.com/vercel/next.js/tree/canary/docs) represent a route segment. These segments are used to generate the URL paths, navigation, and breadcrumbs.
|
|
|
|
The file structure reflects the navigation that you see on the site, and by default, navigation items are sorted alphabetically. However, we can change the order of the items by prepending a two-digit number (`00-`) to the folder or file name.
|
|
|
|
For example, in the [functions API Reference](/docs/app/api-reference/functions), the pages are sorted alphabetically because it makes it easier for developers to find a specific function:
|
|
|
|
```txt
|
|
03-functions
|
|
├── cookies.mdx
|
|
├── draft-mode.mdx
|
|
├── fetch.mdx
|
|
└── ...
|
|
```
|
|
|
|
But, in the [routing section](/docs/app/building-your-application/routing), the files are prefixed with a two-digit number, sorted in the order developers should learn these concepts:
|
|
|
|
```txt
|
|
02-routing
|
|
├── 01-defining-routes.mdx
|
|
├── 02-pages-and-layouts.mdx
|
|
├── 03-linking-and-navigating.mdx
|
|
└── ...
|
|
```
|
|
|
|
To quickly find a page, you can use `⌘ + P` (Mac) or `Ctrl + P` (Windows) to open the search bar on VSCode. Then, type the slug of the page you're looking for. E.g. `defining-routes`
|
|
|
|
> **Why not use a manifest?**
|
|
>
|
|
> We considered using a manifest file (another popular way to generate the docs navigation), but we found that a manifest would quickly get out of sync with the files. File-system routing forces us to think about the structure of the docs and feels more native to Next.js.
|
|
|
|
## Metadata
|
|
|
|
Each page has a metadata block at the top of the file separated by three dashes.
|
|
|
|
### Required Fields
|
|
|
|
The following fields are **required**:
|
|
|
|
| Field | Description |
|
|
| ------------- | ---------------------------------------------------------------------------- |
|
|
| `title` | The page's `<h1>` title, used for SEO and OG Images. |
|
|
| `description` | The page's description, used in the `<meta name="description">` tag for SEO. |
|
|
|
|
```yaml filename="required-fields.mdx"
|
|
---
|
|
title: Page Title
|
|
description: Page Description
|
|
---
|
|
```
|
|
|
|
It's good practice to limit the page title to 2-3 words (e.g. Optimizing Images) and the description to 1-2 sentences (e.g. Learn how to optimize images in Next.js).
|
|
|
|
### Optional Fields
|
|
|
|
The following fields are **optional**:
|
|
|
|
| Field | Description |
|
|
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `nav_title` | Overrides the page's title in the navigation. This is useful when the page's title is too long to fit. If not provided, the `title` field is used. |
|
|
| `source` | Pulls content into a shared page. See [Shared Pages](#shared-pages). |
|
|
| `related` | A list of related pages at the bottom of the document. These will automatically be turned into cards. See [Related Links](#related-links). |
|
|
|
|
```yaml filename="optional-fields.mdx"
|
|
---
|
|
nav_title: Nav Item Title
|
|
source: app/building-your-application/optimizing/images
|
|
related:
|
|
description: See the image component API reference.
|
|
links:
|
|
- app/api-reference/components/image
|
|
---
|
|
```
|
|
|
|
## `App` and `Pages` Docs
|
|
|
|
Since most of the features in the **App Router** and **Pages Router** are completely different, their docs for each are kept in separate sections (`02-app` and `03-pages`). However, there are a few features that are shared between them.
|
|
|
|
### Shared Pages
|
|
|
|
To avoid content duplication and risk the content becoming out of sync, we use the `source` field to pull content from one page into another. For example, the `<Link>` component behaves _mostly_ the same in **App** and **Pages**. Instead of duplicating the content, we can pull the content from `app/.../link.mdx` into `pages/.../link.mdx`:
|
|
|
|
```mdx filename="app/.../link.mdx"
|
|
---
|
|
title: <Link>
|
|
description: API reference for the <Link> component.
|
|
---
|
|
|
|
This API reference will help you understand how to use the props
|
|
and configuration options available for the Link Component.
|
|
```
|
|
|
|
```mdx filename="pages/.../link.mdx"
|
|
---
|
|
title: <Link>
|
|
description: API reference for the <Link> component.
|
|
source: app/api-reference/components/link
|
|
---
|
|
|
|
{/* DO NOT EDIT THIS PAGE. */}
|
|
{/* The content of this page is pulled from the source above. */}
|
|
```
|
|
|
|
We can therefore edit the content in one place and have it reflected in both sections.
|
|
|
|
### Shared Content
|
|
|
|
In shared pages, sometimes there might be content that is **App Router** or **Pages Router** specific. For example, the `<Link>` component has a `shallow` prop that is only available in **Pages** but not in **App**.
|
|
|
|
To make sure the content only shows in the correct router, we can wrap content blocks in an `<AppOnly>` or `<PagesOnly>` components:
|
|
|
|
```mdx filename="app/.../link.mdx"
|
|
This content is shared between App and Pages.
|
|
|
|
<PagesOnly>
|
|
|
|
This content will only be shown on the Pages docs.
|
|
|
|
</PagesOnly>
|
|
|
|
This content is shared between App and Pages.
|
|
```
|
|
|
|
You'll likely use these components for examples and code blocks.
|
|
|
|
## Code Blocks
|
|
|
|
Code blocks should contain a minimum working example that can be copied and pasted. This means that the code should be able to run without any additional configuration.
|
|
|
|
For example, if you're showing how to use the `<Link>` component, you should include the `import` statement and the `<Link>` component itself.
|
|
|
|
```tsx filename="app/page.tsx"
|
|
import Link from 'next/link'
|
|
|
|
export default function Page() {
|
|
return <Link href="/about">About</Link>
|
|
}
|
|
```
|
|
|
|
Always run examples locally before committing them. This will ensure that the code is up-to-date and working.
|
|
|
|
### Language and Filename
|
|
|
|
Code blocks should have a header that includes the language and the `filename`. Add a `filename` prop to render a special Terminal icon that helps orientate users where to input the command. For example:
|
|
|
|
````mdx filename="code-example.mdx"
|
|
```bash filename="Terminal"
|
|
npx create-next-app
|
|
```
|
|
````
|
|
|
|
Most examples in the docs are written in `tsx` and `jsx`, and a few in `bash`. However, you can use any supported language, here's the [full list](https://github.com/shikijs/shiki/blob/main/docs/languages.md#all-languages).
|
|
|
|
When writing JavaScript code blocks, we use the following language and extension combinations.
|
|
|
|
| | Language | Extension |
|
|
| ------------------------------ | -------- | --------- |
|
|
| JavaScript files with JSX code | ```jsx | .js |
|
|
| JavaScript files without JSX | ```js | .js |
|
|
| TypeScript files with JSX | ```tsx | .tsx |
|
|
| TypeScript files without JSX | ```ts | .ts |
|
|
|
|
### TS and JS Switcher
|
|
|
|
Add a language switcher to toggle between TypeScript and JavaScript. Code blocks should be TypeScript first with a JavaScript version to accommodate users.
|
|
|
|
Currently, we write TS and JS examples one after the other, and link them with `switcher` prop:
|
|
|
|
````mdx filename="code-example.mdx"
|
|
```tsx filename="app/page.tsx" switcher
|
|
|
|
```
|
|
|
|
```jsx filename="app/page.js" switcher
|
|
|
|
```
|
|
````
|
|
|
|
> **Good to know**: We plan to automatically compile TypeScript snippets to JavaScript in the future. In the meantime, you can use [transform.tools](https://transform.tools/typescript-to-javascript).
|
|
|
|
### Line Highlighting
|
|
|
|
Code lines can be highlighted. This is useful when you want to draw attention to a specific part of the code. You can highlight lines by passing a number to the `highlight` prop.
|
|
|
|
**Single Line:** `highlight={1}`
|
|
|
|
```tsx filename="app/page.tsx" {1}
|
|
import Link from 'next/link'
|
|
|
|
export default function Page() {
|
|
return <Link href="/about">About</Link>
|
|
}
|
|
```
|
|
|
|
**Multiple Lines:** `highlight={1,3}`
|
|
|
|
```tsx filename="app/page.tsx" highlight={1,3}
|
|
import Link from 'next/link'
|
|
|
|
export default function Page() {
|
|
return <Link href="/about">About</Link>
|
|
}
|
|
```
|
|
|
|
**Range of Lines:** `highlight={1-5}`
|
|
|
|
```tsx filename="app/page.tsx" highlight={1-5}
|
|
import Link from 'next/link'
|
|
|
|
export default function Page() {
|
|
return <Link href="/about">About</Link>
|
|
}
|
|
```
|
|
|
|
## Icons
|
|
|
|
The following icons are available for use in the docs:
|
|
|
|
```mdx filename="mdx-icon.mdx"
|
|
<Check size={18} />
|
|
<Cross size={18} />
|
|
```
|
|
|
|
**Output:**
|
|
|
|
<Check size={18} />
|
|
<Cross size={18} />
|
|
|
|
We do not use emojis in the docs.
|
|
|
|
## Notes
|
|
|
|
For information that is important but not critical, use notes. Notes are a good way to add information without distracting the user from the main content.
|
|
|
|
```mdx filename="notes.mdx"
|
|
> **Good to know**: This is a single line note.
|
|
|
|
> **Good to know**:
|
|
>
|
|
> - We also use this format for multi-line notes.
|
|
> - There are sometimes multiple items worth knowing or keeping in mind.
|
|
```
|
|
|
|
**Output:**
|
|
|
|
> **Good to know**: This is a single line note.
|
|
|
|
> **Good to know**:
|
|
>
|
|
> - We also use this format for multi-line notes.
|
|
> - There are sometimes multiple item worths knowing or keeping in mind.
|
|
|
|
## Related Links
|
|
|
|
Related Links guide the user's learning journey by adding links to logical next steps.
|
|
|
|
- Links will be displayed in cards under the main content of the page.
|
|
- Links will be automatically generated for pages that have child pages. For example, the [Optimizing](/docs/app/building-your-application/optimizing) section has links to all of its child pages.
|
|
|
|
Create related links using the `related` field in the page's metadata.
|
|
|
|
```yaml filename="example.mdx"
|
|
---
|
|
related:
|
|
description: Learn how to quickly get started with your first application.
|
|
links:
|
|
- app/building-your-application/routing/defining-routes
|
|
- app/building-your-application/data-fetching
|
|
- app/api-reference/file-conventions/page
|
|
---
|
|
```
|
|
|
|
### Nested Fields
|
|
|
|
| Field | Required? | Description |
|
|
| ------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `title` | Optional | The title of the card list. Defaults to **Next Steps**. |
|
|
| `description` | Optional | The description of the card list. |
|
|
| `links` | Required | A list of links to other doc pages. Each list item should be a relative URL path (without a leading slash) e.g. `app/api-reference/file-conventions/page` |
|
|
|
|
## Diagrams
|
|
|
|
Diagrams are a great way to explain complex concepts. We use [Figma](https://www.figma.com/) to create diagrams, following Vercel's design guide.
|
|
|
|
The diagrams currently live in the `/public` folder in our private Next.js site. If you'd like to update or add a diagram, please open a [GitHub issue](https://github.com/vercel/next.js/issues/new?assignees=&labels=template%3A+documentation&projects=&template=4.docs_request.yml&title=Docs%3A+) with your ideas.
|
|
|
|
## Custom Components and HTML
|
|
|
|
These are the React Components available for the docs: `<Image />` (next/image), `<PagesOnly />`, `<AppOnly />`, `<Cross />`, and `<Check />`. We do not allow raw HTML in the docs besides the `<details>` tag.
|
|
|
|
If you have ideas for new components, please open a [GitHub issue](https://github.com/vercel/next.js/issues/new/choose).
|
|
|
|
## Style Guide
|
|
|
|
This section contains guidelines for writing docs for those who are new to technical writing.
|
|
|
|
### Page Templates
|
|
|
|
While we don't have a strict template for pages, there are page sections you'll see repeated across the docs:
|
|
|
|
- **Overview:** The first paragraph of a page should tell the user what the feature is and what it's used for. Followed by a minimum working example or its API reference.
|
|
- **Convention:** If the feature has a convention, it should be explained here.
|
|
- **Examples**: Show how the feature can be used with different use cases.
|
|
- **API Tables**: API Pages should have an overview table at the of the page with jump-to-section links (when possible).
|
|
- **Next Steps (Related Links)**: Add links to related pages to guide the user's learning journey.
|
|
|
|
Feel free to add these sections as needed.
|
|
|
|
### Page Types
|
|
|
|
Docs pages are also split into two categories: Conceptual and Reference.
|
|
|
|
- **Conceptual** pages are used to explain a concept or feature. They are usually longer and contain more information than reference pages. In the Next.js docs, conceptual pages are found in the **Building Your Application** section.
|
|
- **Reference** pages are used to explain a specific API. They are usually shorter and more focused. In the Next.js docs, reference pages are found in the **API Reference** section.
|
|
|
|
> **Good to know**: Depending on the page you're contributing to, you may need to follow a different voice and style. For example, conceptual pages are more instructional and use the word _you_ to address the user. Reference pages are more technical, they use more imperative words like "create, update, accept" and tend to omit the word _you_.
|
|
|
|
### Voice
|
|
|
|
Here are some guidelines to maintain a consistent style and voice across the docs:
|
|
|
|
- Write clear, concise sentences. Avoid tangents.
|
|
- If you find yourself using a lot of commas, consider breaking the sentence into multiple sentences or use a list.
|
|
- Swap out complex words for simpler ones. For example, _use_ instead of _utilize_.
|
|
- Be mindful with the word _this_. It can be ambiguous and confusing, don't be afraid to repeat the subject of the sentence if unclear.
|
|
- For example, _Next.js uses React_ instead of _Next.js uses this_.
|
|
- Use an active voice instead of passive. An active sentence is easier to read.
|
|
- For example, _Next.js uses React_ instead of _React is used by Next.js_. If you find yourself using words like _was_ and _by_ you may be using a passive voice.
|
|
- Avoid using words like _easy_, _quick_, _simple_, _just_, etc. This is subjective and can be discouraging to users.
|
|
- Avoid negative words like _don't_, _can't_, _won't_, etc. This can be discouraging to readers.
|
|
- For example, _"You can use the `Link` component to create links between pages"_ instead of _"Don't use the `<a>` tag to create links between pages"_.
|
|
- Write in second person (you/your). This is more personal and engaging.
|
|
- Use gender-neutral language. Use _developers_, _users_, or _readers_, when referring to the audience.
|
|
- If adding code examples, ensure they are properly formatted and working.
|
|
|
|
While these guidelines are not exhaustive, they should help you get started. If you'd like to dive deeper into technical writing, check out the [Google Technical Writing Course](https://developers.google.com/tech-writing/overview).
|
|
|
|
---
|
|
|
|
Thank you for contributing to the docs and being part of the Next.js community!
|
|
|
|
{/* To do: Latest Contributors Component */}
|