docs: new and improve lexical docs, hoist up all headings (#6639)

2024-06-05 17:08:15 -04:00
parent aee3ee21d1
commit 19f8cbcf76
84 changed files with 1215 additions and 1122 deletions
--- a/docs/configuration/collections.mdx
+++ b/docs/configuration/collections.mdx
@@ -35,7 +35,7 @@ It's often best practice to write your Collections in separate files and then im

 _\* An asterisk denotes that a property is required._

-#### Simple collection example
+### Simple collection example

 ```ts
 import { CollectionConfig } from 'payload/types'
@@ -58,13 +58,13 @@ export const Orders: CollectionConfig = {
 }
 ```

-#### More collection config examples
+### More collection config examples

 You can find an assortment
 of [example collection configs](https://github.com/payloadcms/public-demo/tree/master/src/payload/collections) in the Public
 Demo source code on GitHub.

-### Admin options
+## Admin options

 You can customize the way that the Admin panel behaves on a collection-by-collection basis by defining the `admin`
 property on a collection's config.
@@ -87,7 +87,7 @@ property on a collection's config.
 | `listSearchableFields`       | Specify which fields should be searched in the List search view. [More](#list-searchable-fields)                                                                                                      |
 | **`pagination`**             | Set pagination-specific options for this collection. [More](#pagination)                                                                                                                              |

-### Preview
+## Preview

 Collection `admin` options can accept a `preview` function that will be used to generate a link pointing to the frontend
 of your app to preview data.
@@ -126,7 +126,7 @@ export const Posts: CollectionConfig = {
 }
 ```

-### Pagination
+## Pagination

 Here are a few options that you can specify options for pagination on a collection-by-collection basis:

@@ -135,23 +135,23 @@ Here are a few options that you can specify options for pagination on a collecti
 | `defaultLimit` | Integer that specifies the default per-page limit that should be used. Defaults to 10.              |
 | `limits`       | Provide an array of integers to use as per-page options for admins to choose from in the List view. |

-### Access control
+## Access control

 You can specify extremely granular access control (what users can do with documents in a collection) on a collection by
 collection basis. To learn more, go to the [Access Control](/docs/access-control/overview) docs.

-### Hooks
+## Hooks

 Hooks are a powerful way to extend collection functionality and execute your own logic, and can be defined on a
 collection by collection basis. To learn more, go to the [Hooks](/docs/hooks/overview) documentation.

-### Field types
+## Field types

 Collections support all field types that Payload has to offer—including simple fields like text and checkboxes all the
 way to more complicated layout-building field groups like Blocks. [Click here](/docs/fields/overview) to learn more
 about field types.

-### List Searchable Fields
+## List Searchable Fields

 In the List view, there is a "search" box that allows you to quickly find a document with a search. By default, it
 searches on the ID field. If you have `admin.useAsTitle` defined, the list search will use that field. However, you can
@@ -169,7 +169,7 @@ those three fields plus the ID field.
  so your admin queries can remain performant.
 </Banner>

-### TypeScript
+## TypeScript

 You can import collection types as follows:

--- a/docs/configuration/express.mdx
+++ b/docs/configuration/express.mdx
@@ -8,7 +8,7 @@ keywords: config, configuration, documentation, Content Management System, cms,

 Payload utilizes a few Express-specific middleware packages within its own routers. You can customize how they work by passing in configuration options to the main Payload config's `express` property.

-### Custom Middleware
+## Custom Middleware

 Payload allows you to pass in custom Express middleware to be used on all of the routes it opens. This is useful for adding logging or any other custom functionality to your endpoints.

@@ -42,7 +42,7 @@ const requestLoggerMiddleware = (req, res, next) => {
 }
 ```

-### JSON
+## JSON

 `express.json()` is used to parse JSON body content into JavaScript objects accessible on the Express `req`. Payload allows you to customize all of the `json` method's options. Common examples of customization use-cases are increasing the max allowed JSON body size which defaults to `2MB`.

@@ -60,7 +60,7 @@ const requestLoggerMiddleware = (req, res, next) => {

 You can find a list of all available options that are able to be passed to `express.json()` [here](https://expressjs.com/en/api.html).

-### Compression
+## Compression

 Payload uses the `compression` package to optimize transfer size for all of the routes it opens, and you can pass customization options through the Payload config.

--- a/docs/configuration/globals.mdx
+++ b/docs/configuration/globals.mdx
@@ -30,7 +30,7 @@ As with Collection configs, it's often best practice to write your Globals in se

 _\* An asterisk denotes that a property is required._

-#### Simple Global example
+### Simple Global example

 ```ts
 import { GlobalConfig } from 'payload/types'
@@ -58,11 +58,11 @@ const Nav: GlobalConfig = {
 export default Nav
 ```

-#### Global config example
+### Global config example

 You can find a few [example Global configs](https://github.com/payloadcms/public-demo/tree/master/src/payload/globals) in the Public Demo source code on GitHub.

-### Admin options
+## Admin options

 You can customize the way that the Admin panel behaves on a Global-by-Global basis by defining the `admin` property on a Global's config.

@@ -76,7 +76,7 @@ You can customize the way that the Admin panel behaves on a Global-by-Global bas
 | `hideAPIURL`  | Hides the "API URL" meta field while editing documents within this collection.                                                    |
 | `meta`        | Metadata overrides to apply to the [Admin panel](../admin/overview). Included properties are `description` and `openGraph`.       |

-### Preview
+## Preview

 Global `admin` options can accept a `preview` function that will be used to generate a link pointing to the frontend of your app to preview data.

@@ -113,19 +113,19 @@ export const MyGlobal: GlobalConfig = {
 }
 ```

-### Access control
+## Access control

 As with Collections, you can specify extremely granular access control (what users can do with this Global) on a Global-by-Global basis. However, Globals only have `update` and `read` access control due to their nature of only having one document. To learn more, go to the [Access Control](/docs/access-control/overview) docs.

-### Hooks
+## Hooks

 Globals also fully support a smaller subset of Hooks. To learn more, go to the [Hooks](/docs/hooks/overview) documentation.

-### Field types
+## Field types

 Globals support all field types that Payload has to offer—including simple fields like text and checkboxes all the way to more complicated layout-building field groups like Blocks. [Click here](/docs/fields/overview) to learn more about field types.

-### TypeScript
+## TypeScript

 You can import global types as follows:

--- a/docs/configuration/i18n.mdx
+++ b/docs/configuration/i18n.mdx
@@ -56,7 +56,7 @@ export const Articles: CollectionConfig = {
 }
 ```

-### Admin UI
+## Admin UI

 The Payload admin panel reads the language settings of a user's browser and display all text in that language, or will fall back to English if the user's language is not yet supported.
 After a user logs in, they can change their language selection in the `/account` view.
@@ -68,13 +68,13 @@ After a user logs in, they can change their language selection in the `/account`
  [contributions](https://github.com/payloadcms/payload/blob/main/CONTRIBUTING.md).
 </Banner>

-### Node Express
+## Node Express

 Payload's backend uses express middleware to set the language on incoming requests before they are handled. This allows backend validation to return error messages in the user's own language or system generated emails to be sent using the correct translation. You can make HTTP requests with the `accept-language` header and Payload will use that language.

 Anywhere in your Payload app that you have access to the `req` object, you can access payload's extensive internationalization features assigned to `req.i18n`. To access text translations you can use `req.t('namespace:key')`.

-### Configuration Options
+## Configuration Options

 In your Payload config, you can add translations and customize the settings in `i18n`. Payload will use your custom options and merge it with the default, allowing you to override the settings Payload provides.

--- a/docs/configuration/localization.mdx
+++ b/docs/configuration/localization.mdx
@@ -9,7 +9,7 @@ keywords: localization, internationalization, i18n, config, configuration, docum
 Payload features deep field-based localization support. Maintaining as many locales as you need is easy. All
 localization support is opt-in by default. To do so, follow the two steps below.

-### Enabling in the Payload config
+## Enabling in the Payload config

 Add the `localization` property to your Payload config to enable localization project-wide. You'll need to provide a
 list of all locales that you'd like to support as well as set a few other options.
@@ -103,7 +103,7 @@ right-to-left), and `fallbackLocale` property. The locale codes do not need to b
 to define how to represent your locales. Common patterns are to use two-letter ISO 639 language codes or four-letter
 language and country codes (ISO 3166‑1) such as `en-US`, `en-UK`, `es-MX`, etc.

-### Locale Properties:
+## Locale Object Properties

 | Option               | Description                                                                                                                    |
 | -------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
@@ -125,7 +125,7 @@ Boolean enabling "fallback" locale functionality. If a document is requested in
 localized value corresponding to the requested locale, then if this property is enabled, the document will automatically
 fall back to the fallback locale value. If this property is not enabled, the value will not be populated.

-### Field by field localization
+## Field by field localization

 Payload localization works on a **field** level—not a document level. In addition to configuring the base Payload config
 to support localization, you need to specify each field that you would like to localize.
@@ -166,12 +166,12 @@ and `block`s.
  strategy.
 </Banner>

-### Retrieving localized docs
+## Retrieving localized docs

 When retrieving documents, you can specify which locale you'd like to receive as well as which fallback locale should be
 used.

-##### REST API
+#### REST API

 REST API locale functionality relies on URL query parameters.

@@ -190,7 +190,7 @@ valid locale as provided to your base Payload config, or `'null'`, `'false'`, or
 fetch('https://localhost:3000/api/pages?locale=es&fallback-locale=none');
 ```

-##### GraphQL API
+#### GraphQL API

 In the GraphQL API, you can specify `locale` and `fallbackLocale` args to all relevant queries and mutations.

@@ -218,7 +218,7 @@ query {
  arguments in nested related document queries.
 </Banner>

-##### Local API
+#### Local API

 You can specify `locale` as well as `fallbackLocale` within the Local API as well as properties on the `options`
 argument. The `locale` property will accept any valid locale, and the `fallbackLocale` property will accept any valid
--- a/docs/configuration/overview.mdx
+++ b/docs/configuration/overview.mdx
@@ -49,7 +49,7 @@ Payload is a _config-based_, code-first CMS and application framework. The Paylo

 _\* An asterisk denotes that a property is required._

-#### Simple example
+### Simple example

 ```ts
 import { buildConfig } from 'payload/config'
@@ -106,11 +106,11 @@ export default buildConfig({
 })
 ```

-#### Full example config
+### Full example config

 You can see a full [example config](https://github.com/payloadcms/public-demo/blob/master/src/payload/payload.config.ts) in the Public Demo source code on GitHub.

-### Using environment variables in your config
+## Using environment variables in your config

 We suggest using the `dotenv` package to handle environment variables alongside of Payload. All that's necessary to do is to require the package as high up in your application as possible (for example, at the top of your `server.js` file), and ensure that it can find an `.env` file that you create.

@@ -142,7 +142,7 @@ project-name
  can access it. [Click here](/docs/admin/webpack#admin-environment-vars) for more info.
 </Banner>

-### Customizing & Automating Config Location Detection
+## Customizing & Automating Config Location Detection

 Payload is designed to automatically locate your configuration file. By default, it will first look in the root of your current working directory for a file named `payload.config.js` or `payload.config.ts` if you're using TypeScript.

@@ -152,7 +152,7 @@ In production mode, Payload will first attempt to find the config file in the ou

 Please ensure your `tsconfig.json` is properly configured if you want Payload to accurately auto-detect your configuration file location. If `tsconfig.json` does not exist or doesn't specify `rootDir` or `outDir`, Payload will default to the current working directory.

-#### Overriding the Config Location
+### Overriding the Config Location

 In addition to the above automated detection, you can specify your own location for the Payload config file. This is done by using the environment variable `PAYLOAD_CONFIG_PATH`. The path you provide via this environment variable can either be absolute or relative to your current working directory. This can be useful in situations where your Payload config is not in a standard location, or you wish to switch between multiple configurations.

@@ -168,11 +168,11 @@ In addition to the above automated detection, you can specify your own location

 When `PAYLOAD_CONFIG_PATH` is set, Payload will use this path to load the configuration, bypassing all automated detection.

-### Developing within the Config
+## Developing within the Config

 Payload comes with `isomorphic-fetch` installed which means that even in Node, you can use the `fetch` API just as you would within the browser. No need to import `axios` or similar, unless you want to!

-### TypeScript
+## TypeScript

 You can import config types as follows:

@@ -190,7 +190,7 @@ import { SanitizedConfig } from 'payload/config'
 // Generally, this is only used internally by Payload.
 ```

-### Telemetry
+## Telemetry

 Payload collects **completely anonymous** telemetry data about general usage. This data is super important to us and helps us accurately understand how we're growing and what we can do to build the software into everything that it can possibly be. The telemetry that we collect also help us demonstrate our growth in an accurate manner, which helps us as we seek investment to build and scale our team. If we can accurately demonstrate our growth, we can more effectively continue to support Payload as free and open-source software. To opt out of telemetry, you can pass `telemetry: false` within your Payload config.