Skip to content

Commit

Permalink
docs: refactor and improve rich text docs (#9929)
Browse files Browse the repository at this point in the history
- Refactoring that simplifies finding things:
    ```md
    ## BEFORE
    
    - Rich Text
      - Overview
      - Slate
      - Lexical
    - Lexical
      - Overview
      - Converters
      - Migration
      - Custom Features
    
    ## AFTER
    
    - Rich Text
      - Overview
      - Converters
      - Custom Features
      - Migration
      - Slate (legacy) 
    ```

- It takes some of the spotlight away from Slate. Lexical is assumed as
the default editor and a banner at the beginning refers to the Slate
documentation.
- Various writing improvements.

PENDING:
- [ ] some 301 redirects needed
  - `/docs/rich-text/lexical` to `/docs/rich-text/overview`
  - `/docs/lexical/overview` to `/docs/rich-text/overview`
  - `/docs/lexical/converters` to `/docs/rich-text/converters`
  - `/docs/lexical/migration` to `/docs/rich-text/migration`
  • Loading branch information
GermanJablo authored Dec 12, 2024
1 parent 0d8643a commit abee24e
Show file tree
Hide file tree
Showing 8 changed files with 305 additions and 334 deletions.
30 changes: 10 additions & 20 deletions docs/fields/rich-text.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,13 @@ desc: The Rich Text field allows dynamic content to be written through the Admin
keywords: rich text, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs
---

The Rich Text Field is a powerful way to allow editors to write dynamic content. The content is saved as JSON in the database and can be converted into any format, including HTML, that you need.
The Rich Text Field lets editors write and format dynamic content in a familiar interface.
The content is saved as JSON in the database and can be converted to HTML or any other format needed.

Consistent with Payload's goal of making you learn as little of Payload as possible, customizing
and using the Rich Text Editor does not involve learning how to develop for a Payload rich text editor.
Instead, you can invest your time and effort into learning the underlying open-source tools that will allow
you to apply your learnings elsewhere as well.

<LightDarkImage
srcLight="https://payloadcms.com/images/docs/fields/richtext.png"
Expand All @@ -15,23 +21,6 @@ The Rich Text Field is a powerful way to allow editors to write dynamic content.
caption="Admin Panel screenshot of a Rich Text field"
/>

Payload's rich text field is built on an "adapter pattern" which lets you specify which rich text editor you'd like to use.

Right now, Payload is officially supporting two rich text editors:

1. [SlateJS](/docs/rich-text/slate) - legacy, backwards-compatible with 1.0
2. [Lexical](/docs/lexical/overview) - recommended

<Banner type="success">
<strong>
Consistent with Payload's goal of making you learn as little of Payload as possible, customizing
and using the Rich Text Editor does not involve learning how to develop for a{' '}<em>Payload</em>{' '}rich text editor.
</strong>

Instead, you can invest your time and effort into learning the underlying open-source tools that
will allow you to apply your learnings elsewhere as well.
</Banner>

## Config Options

| Option | Description |
Expand All @@ -47,7 +36,7 @@ Right now, Payload is officially supporting two rich text editors:
| **`localized`** | Enable localization for this field. Requires [localization to be enabled](/docs/configuration/localization) in the Base config. |
| **`required`** | Require this field to have a value. |
| **`admin`** | Admin-specific configuration. [More details](#admin-options). |
| **`editor`** | Override the rich text editor specified in your base configuration for this field. |
| **`editor`** | Customize or override the rich text editor. [More details](/docs/rich-text/overview). |
| **`custom`** | Extension point for adding custom data (e.g. for plugins) |
| **`typescriptSchema`** | Override field type generation with providing a JSON schema |
| **`virtual`** | Provide `true` to disable field in the database. See [Virtual Fields](https://payloadcms.com/blog/learn-how-virtual-fields-can-help-solve-common-cms-challenges) |
Expand Down Expand Up @@ -79,4 +68,5 @@ The Rich Text Field inherits all of the default options from the base [Field Adm

## Editor-specific Options

For a ton more editor-specific options, including how to build custom rich text elements directly into your editor, take a look at either the [Slate docs](/docs/rich-text/slate) or the [Lexical docs](/docs/lexical/overview) depending on which editor you're using.
For a ton more editor-specific options, including how to build custom rich text elements directly into your editor,
take a look at the [rich text editor documentation](/docs/rich-text/overview).
292 changes: 0 additions & 292 deletions docs/lexical/overview.mdx

This file was deleted.

File renamed without changes.
File renamed without changes.
9 changes: 0 additions & 9 deletions docs/rich-text/lexical.mdx

This file was deleted.

Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: Lexical Migration
label: Migration
order: 30
order: 90
desc: Migration from slate and payload-plugin-lexical to lexical
keywords: lexical, rich text, editor, headless cms, migrate, migration
---
Expand Down
Loading

0 comments on commit abee24e

Please sign in to comment.