Skip to content

Commit 9c0a8ce

Browse files
ryo-manbastyfle
ryo-manba
and
styfle
authored
Docs: Unify note formatting (vercel#48417)
<!-- Thanks for opening a PR! Your contribution is much appreciated. To make sure your PR is handled as smoothly as possible we request that you follow the checklist sections below. Choose the right checklist for the change(s) that you're making: ## For Contributors ### Improving Documentation or adding/fixing Examples - The "examples guidelines" are followed from our contributing doc https://github.com/vercel/next.js/blob/canary/contributing/examples/adding-examples.md - Make sure the linting passes by running `pnpm build && pnpm lint`. See https://github.com/vercel/next.js/blob/canary/contributing/repository/linting.md ### Fixing a bug - Related issues linked using `fixes #number` - Tests added. See: https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs - Errors have a helpful link attached, see https://github.com/vercel/next.js/blob/canary/contributing.md ### Adding a feature - Implements an existing feature request or RFC. Make sure the feature request has been accepted for implementation before opening a PR. (A discussion must be opened, see https://github.com/vercel/next.js/discussions/new?category=ideas) - Related issues/discussions are linked using `fixes #number` - e2e tests added (https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs - Documentation added - Telemetry added. In case of a feature if it's used or not. - Errors have a helpful link attached, see https://github.com/vercel/next.js/blob/canary/contributing.md ## For Maintainers - Minimal description (aim for explaining to someone not on the team to understand the PR) - When linking to a Slack thread, you might want to share details of the conclusion - Link both the Linear (Fixes NEXT-xxx) and the GitHub issues - Add review comments if necessary to explain to the reviewer the logic behind a change ### What? ### Why? ### How? Closes NEXT- Fixes # --> closes vercel#48416 ### What? Standardize the "Note" format in the Next.js documentation for improved consistency and readability. ### Why? There are currently four different variations of "Note" formatting in the documentation. Standardizing to a single format will improve the overall experience for users. ### How? Update all instances of "Note" in the documentation to follow the most common format, `**Note**:` (used in 27 files). This will involve updating the following variations: - `Note` (12 files) - `Note:` (20 files) - `**Note:**` (21 files) --------- Co-authored-by: Steven <[email protected]>
1 parent f078da3 commit 9c0a8ce

37 files changed

+71
-71
lines changed

‎contributing/docs/adding-documentation.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -37,4 +37,4 @@ After:
3737
]
3838
```
3939

40-
Note: the manifest is checked automatically in the "lint" step in CI when opening a PR.
40+
> **Note**: The manifest is checked automatically in the "lint" step in CI when opening a PR.

‎docs/advanced-features/automatic-static-optimization.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ The cases where the query will be updated after hydration triggering another ren
2828

2929
To be able to distinguish if the query is fully updated and ready for use, you can leverage the `isReady` field on [`next/router`](/docs/api-reference/next/router.md#router-object).
3030

31-
> **Note:** Parameters added with [dynamic routes](/docs/routing/dynamic-routes.md) to a page that's using [`getStaticProps`](/docs/basic-features/data-fetching/get-static-props.md) will always be available inside the `query` object.
31+
> **Note**: Parameters added with [dynamic routes](/docs/routing/dynamic-routes.md) to a page that's using [`getStaticProps`](/docs/basic-features/data-fetching/get-static-props.md) will always be available inside the `query` object.
3232
3333
`next build` will emit `.html` files for statically optimized pages. For example, the result for the page `pages/about.js` would be:
3434

‎docs/advanced-features/custom-document.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ Or add a `className` to the `body` tag:
5050

5151
## Customizing `renderPage`
5252

53-
> **Note:** This is advanced and only needed for libraries like CSS-in-JS to support server-side rendering. This is not needed for built-in `styled-jsx` support.
53+
> **Note**: This is advanced and only needed for libraries like CSS-in-JS to support server-side rendering. This is not needed for built-in `styled-jsx` support.
5454
5555
For [React 18](/docs/advanced-features/react-18.md) support, we recommend avoiding customizing `getInitialProps` and `renderPage`, if possible.
5656

‎docs/advanced-features/custom-server.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ description: Start a Next.js app programmatically using a custom server.
1414

1515
By default, Next.js includes its own server with `next start`. If you have an existing backend, you can still use it with Next.js (this is not a custom server). A custom Next.js server allows you to start a server 100% programmatically in order to use custom server patterns. Most of the time, you will not need this – but it's available for complete customization.
1616

17-
> **Note:** A custom server **cannot** be deployed on [Vercel](https://vercel.com/solutions/nextjs).
17+
> **Note**: A custom server **cannot** be deployed on [Vercel](https://vercel.com/solutions/nextjs).
1818
1919
> Before deciding to use a custom server, please keep in mind that it should only be used when the integrated router of Next.js can't meet your app requirements. A custom server will remove important performance optimizations, like **serverless functions** and **[Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md).**
2020

‎docs/advanced-features/debugging.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -97,7 +97,7 @@ Windows users may run into an issue when using `NODE_OPTIONS='--inspect'` as tha
9797

9898
`cross-env` will set the `NODE_OPTIONS` environment variable regardless of which platform you are on (including Mac, Linux, and Windows) and allow you to debug consistently across devices and operating systems.
9999

100-
> **Note:** Ensure Windows Defender is disabled on your machine. This external service will check _every file read_, which has been reported to greatly increase Fast Refresh time with `next dev`. This is a known issue, not related to Next.js, but it does affect Next.js development.
100+
> **Note**: Ensure Windows Defender is disabled on your machine. This external service will check _every file read_, which has been reported to greatly increase Fast Refresh time with `next dev`. This is a known issue, not related to Next.js, but it does affect Next.js development.
101101
102102
## More information
103103

‎docs/advanced-features/i18n-routing.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -361,4 +361,4 @@ export async function getStaticProps({ locale }) {
361361
- `locales`: 100 total locales
362362
- `domains`: 100 total locale domain items
363363
364-
> **Note:** These limits have been added initially to prevent potential [performance issues at build time](#dynamic-routes-and-getStaticProps-pages). You can workaround these limits with custom routing using [Middleware](/docs/middleware.md) in Next.js 12.
364+
> **Note**: These limits have been added initially to prevent potential [performance issues at build time](#dynamic-routes-and-getStaticProps-pages). You can workaround these limits with custom routing using [Middleware](/docs/middleware.md) in Next.js 12.

‎docs/advanced-features/middleware.md

+4-4
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ Middleware allows you to run code before a request is completed, then based on t
2121

2222
Middleware runs _before_ cached content, so you can personalize static files and pages. Common examples of Middleware would be authentication, A/B testing, localized pages, bot protection, and more. Regarding localized pages, you can start with [i18n routing](/docs/advanced-features/i18n-routing) and implement Middleware for more advanced use cases.
2323

24-
> **Note:** If you were using Middleware prior to `12.2`, please see the [upgrade guide](https://nextjs.org/docs/messages/middleware-upgrade-guide).
24+
> **Note**: If you were using Middleware prior to `12.2`, please see the [upgrade guide](https://nextjs.org/docs/messages/middleware-upgrade-guide).
2525
2626
## Using Middleware
2727

@@ -105,7 +105,7 @@ export const config = {
105105
}
106106
```
107107

108-
> **Note:** The `matcher` values need to be constants so they can be statically analyzed at build-time. Dynamic values such as variables will be ignored.
108+
> **Note**: The `matcher` values need to be constants so they can be statically analyzed at build-time. Dynamic values such as variables will be ignored.
109109
110110
Configured matchers:
111111

@@ -116,7 +116,7 @@ Configured matchers:
116116

117117
Read more details on [path-to-regexp](https://github.com/pillarjs/path-to-regexp#path-to-regexp-1) documentation.
118118

119-
> **Note:** For backward compatibility, Next.js always considers `/public` as `/public/index`. Therefore, a matcher of `/public/:path` will match.
119+
> **Note**: For backward compatibility, Next.js always considers `/public` as `/public/index`. Therefore, a matcher of `/public/:path` will match.
120120
121121
### Conditional Statements
122122

@@ -221,7 +221,7 @@ export function middleware(request: NextRequest) {
221221
}
222222
```
223223

224-
> **Note:** Avoid setting large headers as it might cause [431 Request Header Fields Too Large](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/431) error depending on your backend web server configuration.
224+
> **Note**: Avoid setting large headers as it might cause [431 Request Header Fields Too Large](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/431) error depending on your backend web server configuration.
225225
226226
## Producing a Response
227227

‎docs/advanced-features/module-path-aliases.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -13,9 +13,9 @@ description: Configure module path aliases that allow you to remap certain impor
1313

1414
Next.js automatically supports the `tsconfig.json` and `jsconfig.json` `"paths"` and `"baseUrl"` options since [Next.js 9.4](https://nextjs.org/blog/next-9-4).
1515

16-
> Note: `jsconfig.json` can be used when you don't use TypeScript
16+
> **Note**: `jsconfig.json` can be used when you don't use TypeScript
1717
18-
> Note: you need to restart dev server to reflect modifications done in `tsconfig.json` / `jsconfig.json`
18+
> **Note**: you need to restart dev server to reflect modifications done in `tsconfig.json` / `jsconfig.json`
1919
2020
These options allow you to configure module aliases, for example a common pattern is aliasing certain directories to use absolute paths.
2121

‎docs/advanced-features/open-telemetry.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ This documentation uses terms like _Span_, _Trace_ or _Exporter_ throughout this
1919
Next.js supports OpenTelemetry instrumentation out of the box, which means that we already instrumented Next.js itself.
2020
When you enable OpenTelemetry we will automatically wrap all your code like `getStaticProps` in _spans_ with helpful attributes.
2121

22-
> **Note:** We currently support OpenTelemetry bindings only in serverless functions.
22+
> **Note**: We currently support OpenTelemetry bindings only in serverless functions.
2323
> We don't provide any for `edge` or client side code.
2424
2525
## Getting Started

‎docs/advanced-features/output-file-tracing.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -34,9 +34,9 @@ This will create a folder at `.next/standalone` which can then be deployed on it
3434

3535
Additionally, a minimal `server.js` file is also output which can be used instead of `next start`. This minimal server does not copy the `public` or `.next/static` folders by default as these should ideally be handled by a CDN instead, although these folders can be copied to the `standalone/public` and `standalone/.next/static` folders manually, after which `server.js` file will serve these automatically.
3636

37-
Note: `next.config.js` is read during `next build` and serialized into the `server.js` output file. If the legacy [`serverRuntimeConfig` or `publicRuntimeConfig` options](/docs/api-reference/next.config.js/runtime-configuration.md) are being used, the values will be specific to values at build time.
37+
> **Note**: `next.config.js` is read during `next build` and serialized into the `server.js` output file. If the legacy [`serverRuntimeConfig` or `publicRuntimeConfig` options](/docs/api-reference/next.config.js/runtime-configuration.md) are being used, the values will be specific to values at build time.
3838
39-
If your project uses [Image Optimization](/docs/basic-features/image-optimization.md) with the default `loader`, you must install `sharp` as a dependency:
39+
> **Note**: If your project uses [Image Optimization](/docs/basic-features/image-optimization.md) with the default `loader`, you must install `sharp` as a dependency:
4040
4141
```bash
4242
npm i sharp

‎docs/advanced-features/preview-mode.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -243,7 +243,7 @@ export default function myApiRoute(req, res) {
243243
Both the bypass cookie value and the private key for encrypting the `previewData` change when `next build` is completed.
244244
This ensures that the bypass cookie can’t be guessed.
245245

246-
> **Note:** To test Preview Mode locally over HTTP your browser will need to allow third-party cookies and local storage access.
246+
> **Note**: To test Preview Mode locally over HTTP your browser will need to allow third-party cookies and local storage access.
247247
248248
## Learn more
249249

‎docs/api-reference/cli.md

+4-4
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ NODE_OPTIONS='-r esm' next
3939
NODE_OPTIONS='--inspect' next
4040
```
4141

42-
> Note: Running `next` without a command is the same as running `next dev`
42+
> **Note**: Running `next` without a command is the same as running `next dev`
4343
4444
## Build
4545

@@ -82,7 +82,7 @@ Or using the `PORT` environment variable:
8282
PORT=4000 npx next dev
8383
```
8484

85-
> Note: `PORT` cannot be set in `.env` as booting up the HTTP server happens before any other code is initialized.
85+
> **Note**: `PORT` cannot be set in `.env` as booting up the HTTP server happens before any other code is initialized.
8686
8787
You can also set the hostname to be different from the default of `0.0.0.0`, this can be useful for making the application available for other devices on the network. The default hostname can be changed with `-H`, like so:
8888

@@ -106,9 +106,9 @@ Or using the `PORT` environment variable:
106106
PORT=4000 npx next start
107107
```
108108

109-
> Note: `PORT` cannot be set in `.env` as booting up the HTTP server happens before any other code is initialized.
109+
> **Note**: `PORT` cannot be set in `.env` as booting up the HTTP server happens before any other code is initialized.
110110
111-
> Note: `next start` cannot be used with `output: 'standalone'` or `output: 'export'`.
111+
> **Note**: `next start` cannot be used with `output: 'standalone'` or `output: 'export'`.
112112
113113
### Keep Alive Timeout
114114

‎docs/api-reference/data-fetching/get-static-paths.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -126,7 +126,7 @@ If `fallback` is `true`, then the behavior of `getStaticProps` changes in the fo
126126
- When complete, the browser receives the `JSON` for the generated path. This will be used to automatically render the page with the required props. From the user’s perspective, the page will be swapped from the fallback page to the full page.
127127
- At the same time, Next.js adds this path to the list of pre-rendered pages. Subsequent requests to the same path will serve the generated page, like other pages pre-rendered at build time.
128128

129-
> **Note:** `fallback: true` is not supported when using [`output: 'export'`](/docs/advanced-features/static-html-export.md).
129+
> **Note**: `fallback: true` is not supported when using [`output: 'export'`](/docs/advanced-features/static-html-export.md).
130130
131131
#### When is `fallback: true` useful?
132132

@@ -153,7 +153,7 @@ If `fallback` is `'blocking'`, new paths not returned by `getStaticPaths` will w
153153

154154
`fallback: 'blocking'` will not _update_ generated pages by default. To update generated pages, use [Incremental Static Regeneration](/docs/basic-features/data-fetching/incremental-static-regeneration.md) in conjunction with `fallback: 'blocking'`.
155155

156-
> **Note:** `fallback: 'blocking'` is not supported when using [`output: 'export'`](/docs/advanced-features/static-html-export.md).
156+
> **Note**: `fallback: 'blocking'` is not supported when using [`output: 'export'`](/docs/advanced-features/static-html-export.md).
157157
158158
### Fallback pages
159159

‎docs/api-reference/next.config.js/basepath.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ module.exports = {
2323
}
2424
```
2525

26-
Note: this value must be set at build time and can not be changed without re-building as the value is inlined in the client-side bundles.
26+
> **Note**: This value must be set at build time and cannot be changed without re-building as the value is inlined in the client-side bundles.
2727
2828
## Links
2929

‎docs/api-reference/next.config.js/build-indicator.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ description: In development mode, pages include an indicator to let you know if
66

77
When you edit your code, and Next.js is compiling the application, a compilation indicator appears in the bottom right corner of the page.
88

9-
> **Note:** This indicator is only present in development mode and will not appear when building and running the app in production mode.
9+
> **Note**: This indicator is only present in development mode and will not appear when building and running the app in production mode.
1010
1111
In some cases this indicator can be misplaced on your page, for example, when conflicting with a chat launcher. To change its position, open `next.config.js` and set the `buildActivityPosition` in the `devIndicators` object to `bottom-right` (default), `bottom-left`, `top-right` or `top-left`:
1212

‎docs/api-reference/next.config.js/custom-webpack-config.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ description: Extend the default webpack config added by Next.js.
44

55
# Custom Webpack Config
66

7-
> Note: changes to webpack config are not covered by semver so proceed at your own risk
7+
> **Note**: changes to webpack config are not covered by semver so proceed at your own risk
88
99
Before continuing to add custom webpack configuration to your application make sure Next.js doesn't already support your use-case:
1010

‎docs/api-reference/next.config.js/exportPathMap.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ module.exports = {
4040
}
4141
```
4242

43-
> Note: the `query` field in `exportPathMap` cannot be used with [automatically statically optimized pages](/docs/advanced-features/automatic-static-optimization) or [`getStaticProps` pages](/docs/basic-features/data-fetching/get-static-props.md) as they are rendered to HTML files at build-time and additional query information cannot be provided during `next export`.
43+
> **Note**: the `query` field in `exportPathMap` cannot be used with [automatically statically optimized pages](/docs/advanced-features/automatic-static-optimization) or [`getStaticProps` pages](/docs/basic-features/data-fetching/get-static-props.md) as they are rendered to HTML files at build-time and additional query information cannot be provided during `next export`.
4444
4545
The pages will then be exported as HTML files, for example, `/about` will become `/about.html`.
4646

‎docs/api-reference/next.config.js/redirects.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -311,7 +311,7 @@ module.exports = {
311311
}
312312
```
313313

314-
In some rare cases, you might need to assign a custom status code for older HTTP Clients to properly redirect. In these cases, you can use the `statusCode` property instead of the `permanent` property, but not both. Note: to ensure IE11 compatibility a `Refresh` header is automatically added for the 308 status code.
314+
In some rare cases, you might need to assign a custom status code for older HTTP Clients to properly redirect. In these cases, you can use the `statusCode` property instead of the `permanent` property, but not both. To to ensure IE11 compatibility, a `Refresh` header is automatically added for the 308 status code.
315315

316316
## Other Redirects
317317

‎docs/api-reference/next.config.js/rewrites.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,7 @@ module.exports = {
8989
}
9090
```
9191

92-
Note: rewrites in `beforeFiles` do not check the filesystem/dynamic routes immediately after matching a source, they continue until all `beforeFiles` have been checked.
92+
> **Note**: rewrites in `beforeFiles` do not check the filesystem/dynamic routes immediately after matching a source, they continue until all `beforeFiles` have been checked.
9393
9494
The order Next.js routes are checked is:
9595

@@ -150,7 +150,7 @@ module.exports = {
150150
}
151151
```
152152

153-
Note: for static pages from the [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md) or [prerendering](/docs/basic-features/data-fetching/get-static-props.md) params from rewrites will be parsed on the client after hydration and provided in the query.
153+
> **Note**: Static pages from [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md) or [prerendering](/docs/basic-features/data-fetching/get-static-props.md) params from rewrites will be parsed on the client after hydration and provided in the query.
154154
155155
## Path Matching
156156

‎docs/api-reference/next.config.js/runtime-configuration.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ description: Add client and server runtime configuration to your Next.js app.
44

55
# Runtime Configuration
66

7-
> Note: This feature is considered legacy and does not work with [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md), [Output File Tracing](/docs/advanced-features/output-file-tracing.md#automatically-copying-traced-files), or [React Server Components](/docs/advanced-features/react-18/server-components.md). Please use [environment variables](/docs/basic-features/environment-variables.md) instead in order to avoid initialization overhead.
7+
> **Note**: This feature is considered legacy and does not work with [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md), [Output File Tracing](/docs/advanced-features/output-file-tracing.md#automatically-copying-traced-files), or [React Server Components](/docs/advanced-features/react-18/server-components.md). Please use [environment variables](/docs/basic-features/environment-variables.md) instead in order to avoid initialization overhead.
88
99
To add runtime configuration to your app, open `next.config.js` and add the `publicRuntimeConfig` and `serverRuntimeConfig` configs:
1010

‎docs/api-reference/next.config.js/static-optimization-indicator.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ description: Optimized pages include an indicator to let you know if it's being
44

55
# Static Optimization Indicator
66

7-
> **Note:** This indicator was removed in Next.js version 10.0.1. We recommend upgrading to the latest version of Next.js.
7+
> **Note**: This indicator was removed in Next.js version 10.0.1. We recommend upgrading to the latest version of Next.js.
88
99
When a page qualifies for [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md) we show an indicator to let you know.
1010

0 commit comments

Comments
 (0)