Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: Unify note formatting #48417

Merged
merged 7 commits into from Apr 19, 2023
Merged
Show file tree
Hide file tree
Changes from 4 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
2 changes: 1 addition & 1 deletion contributing/docs/adding-documentation.md
Expand Up @@ -37,4 +37,4 @@ After:
]
```

Note: the manifest is checked automatically in the "lint" step in CI when opening a PR.
**Note**: the manifest is checked automatically in the "lint" step in CI when opening a PR.
styfle marked this conversation as resolved.
Show resolved Hide resolved
2 changes: 1 addition & 1 deletion docs/advanced-features/automatic-static-optimization.md
Expand Up @@ -28,7 +28,7 @@ The cases where the query will be updated after hydration triggering another ren

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

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

`next build` will emit `.html` files for statically optimized pages. For example, the result for the page `pages/about.js` would be:

Expand Down
2 changes: 1 addition & 1 deletion docs/advanced-features/custom-document.md
Expand Up @@ -50,7 +50,7 @@ Or add a `className` to the `body` tag:

## Customizing `renderPage`

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

For [React 18](/docs/advanced-features/react-18.md) support, we recommend avoiding customizing `getInitialProps` and `renderPage`, if possible.

Expand Down
2 changes: 1 addition & 1 deletion docs/advanced-features/custom-server.md
Expand Up @@ -14,7 +14,7 @@ description: Start a Next.js app programmatically using a custom server.

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.

> **Note:** A custom server **cannot** be deployed on [Vercel](https://vercel.com/solutions/nextjs).
> **Note**: A custom server **cannot** be deployed on [Vercel](https://vercel.com/solutions/nextjs).

> 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).**

Expand Down
2 changes: 1 addition & 1 deletion docs/advanced-features/debugging.md
Expand Up @@ -97,7 +97,7 @@ Windows users may run into an issue when using `NODE_OPTIONS='--inspect'` as tha

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

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

## More information

Expand Down
2 changes: 1 addition & 1 deletion docs/advanced-features/i18n-routing.md
Expand Up @@ -361,4 +361,4 @@ export async function getStaticProps({ locale }) {
- `locales`: 100 total locales
- `domains`: 100 total locale domain items

> **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.
> **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.
8 changes: 4 additions & 4 deletions docs/advanced-features/middleware.md
Expand Up @@ -21,7 +21,7 @@ Middleware allows you to run code before a request is completed, then based on t

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.

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

## Using Middleware

Expand Down Expand Up @@ -105,7 +105,7 @@ export const config = {
}
```

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

Configured matchers:

Expand All @@ -116,7 +116,7 @@ Configured matchers:

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

> **Note:** For backward compatibility, Next.js always considers `/public` as `/public/index`. Therefore, a matcher of `/public/:path` will match.
> **Note**: For backward compatibility, Next.js always considers `/public` as `/public/index`. Therefore, a matcher of `/public/:path` will match.

### Conditional Statements

Expand Down Expand Up @@ -221,7 +221,7 @@ export function middleware(request: NextRequest) {
}
```

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

## Producing a Response

Expand Down
4 changes: 2 additions & 2 deletions docs/advanced-features/module-path-aliases.md
Expand Up @@ -13,9 +13,9 @@ description: Configure module path aliases that allow you to remap certain impor

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

> Note: `jsconfig.json` can be used when you don't use TypeScript
> **Note**: `jsconfig.json` can be used when you don't use TypeScript

> Note: you need to restart dev server to reflect modifications done in `tsconfig.json` / `jsconfig.json`
> **Note**: you need to restart dev server to reflect modifications done in `tsconfig.json` / `jsconfig.json`

These options allow you to configure module aliases, for example a common pattern is aliasing certain directories to use absolute paths.

Expand Down
2 changes: 1 addition & 1 deletion docs/advanced-features/open-telemetry.md
Expand Up @@ -19,7 +19,7 @@ This documentation uses terms like _Span_, _Trace_ or _Exporter_ throughout this
Next.js supports OpenTelemetry instrumentation out of the box, which means that we already instrumented Next.js itself.
When you enable OpenTelemetry we will automatically wrap all your code like `getStaticProps` in _spans_ with helpful attributes.

> **Note:** We currently support OpenTelemetry bindings only in serverless functions.
> **Note**: We currently support OpenTelemetry bindings only in serverless functions.
> We don't provide any for `edge` or client side code.

## Getting Started
Expand Down
2 changes: 1 addition & 1 deletion docs/advanced-features/output-file-tracing.md
Expand Up @@ -34,7 +34,7 @@ This will create a folder at `.next/standalone` which can then be deployed on it

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.

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.
**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.
styfle marked this conversation as resolved.
Show resolved Hide resolved

If your project uses [Image Optimization](/docs/basic-features/image-optimization.md) with the default `loader`, you must install `sharp` as a dependency:
styfle marked this conversation as resolved.
Show resolved Hide resolved

Expand Down
2 changes: 1 addition & 1 deletion docs/advanced-features/preview-mode.md
Expand Up @@ -243,7 +243,7 @@ export default function myApiRoute(req, res) {
Both the bypass cookie value and the private key for encrypting the `previewData` change when `next build` is completed.
This ensures that the bypass cookie can’t be guessed.

> **Note:** To test Preview Mode locally over HTTP your browser will need to allow third-party cookies and local storage access.
> **Note**: To test Preview Mode locally over HTTP your browser will need to allow third-party cookies and local storage access.

## Learn more

Expand Down
8 changes: 4 additions & 4 deletions docs/api-reference/cli.md
Expand Up @@ -39,7 +39,7 @@ NODE_OPTIONS='-r esm' next
NODE_OPTIONS='--inspect' next
```

> Note: Running `next` without a command is the same as running `next dev`
> **Note**: Running `next` without a command is the same as running `next dev`

## Build

Expand Down Expand Up @@ -82,7 +82,7 @@ Or using the `PORT` environment variable:
PORT=4000 npx next dev
```

> Note: `PORT` cannot be set in `.env` as booting up the HTTP server happens before any other code is initialized.
> **Note**: `PORT` cannot be set in `.env` as booting up the HTTP server happens before any other code is initialized.

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:

Expand All @@ -106,9 +106,9 @@ Or using the `PORT` environment variable:
PORT=4000 npx next start
```

> Note: `PORT` cannot be set in `.env` as booting up the HTTP server happens before any other code is initialized.
> **Note**: `PORT` cannot be set in `.env` as booting up the HTTP server happens before any other code is initialized.

> Note: `next start` cannot be used with `output: 'standalone'` or `output: 'export'`.
> **Note**: `next start` cannot be used with `output: 'standalone'` or `output: 'export'`.

### Keep Alive Timeout

Expand Down
4 changes: 2 additions & 2 deletions docs/api-reference/data-fetching/get-static-paths.md
Expand Up @@ -126,7 +126,7 @@ If `fallback` is `true`, then the behavior of `getStaticProps` changes in the fo
- 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.
- 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.

> **Note:** `fallback: true` is not supported when using [`output: 'export'`](/docs/advanced-features/static-html-export.md).
> **Note**: `fallback: true` is not supported when using [`output: 'export'`](/docs/advanced-features/static-html-export.md).

#### When is `fallback: true` useful?

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

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

> **Note:** `fallback: 'blocking'` is not supported when using [`output: 'export'`](/docs/advanced-features/static-html-export.md).
> **Note**: `fallback: 'blocking'` is not supported when using [`output: 'export'`](/docs/advanced-features/static-html-export.md).

### Fallback pages

Expand Down
2 changes: 1 addition & 1 deletion docs/api-reference/next.config.js/basepath.md
Expand Up @@ -23,7 +23,7 @@ module.exports = {
}
```

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.
**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.
styfle marked this conversation as resolved.
Show resolved Hide resolved

## Links

Expand Down
2 changes: 1 addition & 1 deletion docs/api-reference/next.config.js/build-indicator.md
Expand Up @@ -6,7 +6,7 @@ description: In development mode, pages include an indicator to let you know if

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

> **Note:** This indicator is only present in development mode and will not appear when building and running the app in production mode.
> **Note**: This indicator is only present in development mode and will not appear when building and running the app in production mode.

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

Expand Down
Expand Up @@ -4,7 +4,7 @@ description: Extend the default webpack config added by Next.js.

# Custom Webpack Config

> Note: changes to webpack config are not covered by semver so proceed at your own risk
> **Note**: changes to webpack config are not covered by semver so proceed at your own risk

Before continuing to add custom webpack configuration to your application make sure Next.js doesn't already support your use-case:

Expand Down
2 changes: 1 addition & 1 deletion docs/api-reference/next.config.js/exportPathMap.md
Expand Up @@ -40,7 +40,7 @@ module.exports = {
}
```

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

The pages will then be exported as HTML files, for example, `/about` will become `/about.html`.

Expand Down
2 changes: 1 addition & 1 deletion docs/api-reference/next.config.js/redirects.md
Expand Up @@ -311,7 +311,7 @@ module.exports = {
}
```

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.
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.
styfle marked this conversation as resolved.
Show resolved Hide resolved

## Other Redirects

Expand Down
4 changes: 2 additions & 2 deletions docs/api-reference/next.config.js/rewrites.md
Expand Up @@ -89,7 +89,7 @@ module.exports = {
}
```

Note: rewrites in `beforeFiles` do not check the filesystem/dynamic routes immediately after matching a source, they continue until all `beforeFiles` have been checked.
**Note**: rewrites in `beforeFiles` do not check the filesystem/dynamic routes immediately after matching a source, they continue until all `beforeFiles` have been checked.
styfle marked this conversation as resolved.
Show resolved Hide resolved

The order Next.js routes are checked is:

Expand Down Expand Up @@ -150,7 +150,7 @@ module.exports = {
}
```

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.
**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.
styfle marked this conversation as resolved.
Show resolved Hide resolved

## Path Matching

Expand Down
Expand Up @@ -4,7 +4,7 @@ description: Add client and server runtime configuration to your Next.js app.

# Runtime Configuration

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

To add runtime configuration to your app, open `next.config.js` and add the `publicRuntimeConfig` and `serverRuntimeConfig` configs:

Expand Down
Expand Up @@ -4,7 +4,7 @@ description: Optimized pages include an indicator to let you know if it's being

# Static Optimization Indicator

> **Note:** This indicator was removed in Next.js version 10.0.1. We recommend upgrading to the latest version of Next.js.
> **Note**: This indicator was removed in Next.js version 10.0.1. We recommend upgrading to the latest version of Next.js.

When a page qualifies for [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md) we show an indicator to let you know.

Expand Down