9f9db3ff81
## Introducing Prettier for docs
Prettier [was originally disabled for our docs as it didn't support MDX
2.0](1fa636417f),
outputting invalid MDX syntax.
This has since been fixed - prettier now supports MDX 2.0.
## Reducing print width
This also reduces the print width for the docs folder from 100 to 70.
Our docs code field are very narrow - this should help make code more
readable.
**Before**
**After**
**Before**
**After**
243 lines
9.7 KiB
Plaintext
243 lines
9.7 KiB
Plaintext
---
|
|
title: Page Metadata
|
|
label: Metadata
|
|
order: 70
|
|
desc: Customize the metadata of your pages within the Admin Panel
|
|
keywords: admin, components, custom, documentation, Content Management System, cms, headless, javascript, node, react, nextjs
|
|
---
|
|
|
|
Every page within the Admin Panel automatically receives dynamic, auto-generated metadata derived from live document data, the user's current locale, and more. This includes the page title, description, og:image, etc. and requires no additional configuration.
|
|
|
|
Metadata is fully configurable at the root level and cascades down to individual collections, documents, and custom views. This allows for the ability to control metadata on any page with high precision, while also providing sensible defaults.
|
|
|
|
All metadata is injected into Next.js' [`generateMetadata`](https://nextjs.org/docs/app/api-reference/functions/generate-metadata) function. This used to generate the `<head>` of pages within the Admin Panel. All metadata options that are available in Next.js are exposed by Payload.
|
|
|
|
Within the Admin Panel, metadata can be customized at the following levels:
|
|
|
|
- [Root Metadata](#root-metadata)
|
|
- [Collection Metadata](#collection-metadata)
|
|
- [Global Metadata](#global-metadata)
|
|
- [View Metadata](#view-metadata)
|
|
|
|
All of these types of metadata share a similar structure, with a few key differences on the Root level. To customize metadata, consult the list of available scopes. Determine the scope that corresponds to what you are trying to accomplish, then author your metadata within the Payload Config accordingly.
|
|
|
|
## Root Metadata
|
|
|
|
Root Metadata is the metadata that is applied to all pages within the Admin Panel. This is where you can control things like the suffix appended onto each page's title, the favicon displayed in the browser's tab, and the Open Graph data that is used when sharing the Admin Panel on social media.
|
|
|
|
To customize Root Metadata, use the `admin.meta` key in your Payload Config:
|
|
|
|
```ts
|
|
{
|
|
// ...
|
|
admin: {
|
|
// highlight-start
|
|
meta: {
|
|
// highlight-end
|
|
title: 'My Admin Panel',
|
|
description: 'The best admin panel in the world',
|
|
icons: [
|
|
{
|
|
rel: 'icon',
|
|
type: 'image/png',
|
|
url: '/favicon.png',
|
|
},
|
|
],
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
The following options are available for Root Metadata:
|
|
|
|
| Key | Type | Description |
|
|
| -------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `defaultOGImageType` | `dynamic` (default), `static`, or `off` | The type of default OG image to use. If set to `dynamic`, Payload will use Next.js image generation to create an image with the title of the page. If set to `static`, Payload will use the `defaultOGImage` URL. If set to `off`, Payload will not generate an OG image. |
|
|
| `titleSuffix` | `string` | A suffix to append to the end of the title of every page. Defaults to "- Payload". |
|
|
| `[keyof Metadata]` | `unknown` | Any other properties that Next.js supports within the `generateMetadata` function. [More details](https://nextjs.org/docs/app/api-reference/functions/generate-metadata). |
|
|
|
|
<Banner type="success">
|
|
**Reminder:** These are the _root-level_ options for the Admin Panel. You can
|
|
also customize metadata on the [Collection](../configuration/collections),
|
|
[Global](../configuration/globals), and Document levels through their
|
|
respective configs.
|
|
</Banner>
|
|
|
|
### Icons
|
|
|
|
The Icons Config corresponds to the `<link>` tags that are used to specify icons for the Admin Panel. The `icons` key is an array of objects, each of which represents an individual icon. Icons are differentiated from one another by their `rel` attribute, which specifies the relationship between the document and the icon.
|
|
|
|
The most common icon type is the favicon, which is displayed in the browser tab. This is specified by the `rel` attribute `icon`. Other common icon types include `apple-touch-icon`, which is used by Apple devices when the Admin Panel is saved to the home screen, and `mask-icon`, which is used by Safari to mask the Admin Panel icon.
|
|
|
|
To customize icons, use the `admin.meta.icons` property in your Payload Config:
|
|
|
|
```ts
|
|
{
|
|
// ...
|
|
admin: {
|
|
meta: {
|
|
// highlight-start
|
|
icons: [
|
|
// highlight-end
|
|
{
|
|
rel: 'icon',
|
|
type: 'image/png',
|
|
url: '/favicon.png',
|
|
},
|
|
{
|
|
rel: 'apple-touch-icon',
|
|
type: 'image/png',
|
|
url: '/apple-touch-icon.png',
|
|
},
|
|
],
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
For a full list of all available Icon options, see the [Next.js documentation](https://nextjs.org/docs/app/api-reference/functions/generate-metadata#icons).
|
|
|
|
### Open Graph
|
|
|
|
Open Graph metadata is a set of tags that are used to control how URLs are displayed when shared on social media platforms. Open Graph metadata is automatically generated by Payload, but can be customized at the Root level.
|
|
|
|
To customize Open Graph metadata, use the `admin.meta.openGraph` property in your Payload Config:
|
|
|
|
```ts
|
|
{
|
|
// ...
|
|
admin: {
|
|
meta: {
|
|
// highlight-start
|
|
openGraph: {
|
|
// highlight-end
|
|
description: 'The best admin panel in the world',
|
|
images: [
|
|
{
|
|
url: 'https://example.com/image.jpg',
|
|
width: 800,
|
|
height: 600,
|
|
},
|
|
],
|
|
siteName: 'Payload',
|
|
title: 'My Admin Panel',
|
|
},
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
For a full list of all available Open Graph options, see the [Next.js documentation](https://nextjs.org/docs/app/api-reference/functions/generate-metadata#opengraph).
|
|
|
|
### Robots
|
|
|
|
Setting the `robots` property will allow you to control the `robots` meta tag that is rendered within the `<head>` of the Admin Panel. This can be used to control how search engines index pages and displays them in search results.
|
|
|
|
By default, the Admin Panel is set to prevent search engines from indexing pages within the Admin Panel.
|
|
|
|
To customize the Robots Config, use the `admin.meta.robots` property in your Payload Config:
|
|
|
|
```ts
|
|
{
|
|
// ...
|
|
admin: {
|
|
meta: {
|
|
// highlight-start
|
|
robots: 'noindex, nofollow',
|
|
// highlight-end
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
For a full list of all available Robots options, see the [Next.js documentation](https://nextjs.org/docs/app/api-reference/functions/generate-metadata#robots).
|
|
|
|
##### Prevent Crawling
|
|
|
|
While setting meta tags via `admin.meta.robots` can prevent search engines from _indexing_ web pages, it does not prevent them from being _crawled_.
|
|
|
|
To prevent your pages from being crawled altogether, add a `robots.txt` file to your root directory.
|
|
|
|
```text
|
|
User-agent: *
|
|
Disallow: /admin/
|
|
```
|
|
|
|
<Banner type="info">
|
|
**Note:** If you've customized the path to your Admin Panel via
|
|
`config.routes`, be sure to update the `Disallow` directive to match your
|
|
custom path.
|
|
</Banner>
|
|
|
|
## Collection Metadata
|
|
|
|
Collection Metadata is the metadata that is applied to all pages within any given Collection within the Admin Panel. This metadata is used to customize the title and description of all views within any given Collection, unless overridden by the view itself.
|
|
|
|
To customize Collection Metadata, use the `admin.meta` key within your Collection Config:
|
|
|
|
```ts
|
|
import type { CollectionConfig } from 'payload'
|
|
|
|
export const MyCollection: CollectionConfig = {
|
|
// ...
|
|
admin: {
|
|
// highlight-start
|
|
meta: {
|
|
// highlight-end
|
|
title: 'My Collection',
|
|
description: 'The best collection in the world',
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
The Collection Meta config has the same options as the [Root Metadata](#root-metadata) config.
|
|
|
|
## Global Metadata
|
|
|
|
Global Metadata is the metadata that is applied to all pages within any given Global within the Admin Panel. This metadata is used to customize the title and description of all views within any given Global, unless overridden by the view itself.
|
|
|
|
To customize Global Metadata, use the `admin.meta` key within your Global Config:
|
|
|
|
```ts
|
|
import { GlobalConfig } from 'payload'
|
|
|
|
export const MyGlobal: GlobalConfig = {
|
|
// ...
|
|
admin: {
|
|
// highlight-start
|
|
meta: {
|
|
// highlight-end
|
|
title: 'My Global',
|
|
description: 'The best admin panel in the world',
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
The Global Meta config has the same options as the [Root Metadata](#root-metadata) config.
|
|
|
|
## View Metadata
|
|
|
|
View Metadata is the metadata that is applied to specific [Views](../custom-components/custom-views) within the Admin Panel. This metadata is used to customize the title and description of a specific view, overriding any metadata set at the [Root](#root-metadata), [Collection](#collection-metadata), or [Global](#global-metadata) level.
|
|
|
|
To customize View Metadata, use the `meta` key within your View Config:
|
|
|
|
```ts
|
|
{
|
|
// ...
|
|
admin: {
|
|
views: {
|
|
dashboard: {
|
|
// highlight-start
|
|
meta: {
|
|
// highlight-end
|
|
title: 'My Dashboard',
|
|
description: 'The best dashboard in the world',
|
|
}
|
|
},
|
|
},
|
|
},
|
|
}
|
|
```
|