Document field

The document field is a highly customisable rich text editor.

It lets content creators quickly and easily edit content in your system.

Usage example

document: fields.document({
  label: 'Document',
  formatting: true,
  links: true,
  images: true
})

Formatting options

The WYSIWYG toolbar can be customised to allow a range of formatting options. This is done via the formatting option on the document field.

Setting formatting: true will enable all the formatting options that are available in Markdown syntax, but you can also specify only a specific subset of options you want to allow.

The editor features built-in support for some additional common formatting features that require custom Markdoc tags to render, including alignment, underline, subscript and superscript. These aren't included with the shorthand formatting: true option, but can be enabled by passing an object with the relevant options set to true.

The formatting options enabled when using the shorthand are:

{
  formatting: {
    inlineMarks: {
      bold: true,
      italic: true,
      strikethrough: true,
      code: true,
    },
    listTypes: {
      ordered: true,
      unordered: true,
    },
    headingLevels: [1, 2, 3, 4, 5, 6],
    blockTypes: {
      blockquote: true,
      code: true,
    },
    softBreaks: true,
  },
}

The additional formatting options (not on by default) are:

{
  formatting: {
    // this is the same as providing `alignment: true`
    alignment: {
      center: true,
      end: true,
    }.
    inlineMarks: {
      keyboard: true,
      subscript: true,
      superscript: true,
      underline: true,
    },
  },
}

Formatting options type signature

The type signature for the full list of available formatting options is available at: https://docsmill.dev/npm/@keystatic/core@latest#/.fields.document.DocumentFeaturesConfig

Component blocks

The document field can register custom component blocks, which you can use to render custom UI components with props within your document field.

Each component block has its own fields schema, and can be configured with a custom preview component.

document: fields.document({
  label: 'Document',
  formatting: true,
  componentBlocks: {
    quote: component({
      preview: () => null,
      label: 'Quote',
      schema: {
        content: fields.child({
          kind: 'block',
          placeholder: 'Quote...',
          formatting: { inlineMarks: 'inherit', softBreaks: 'inherit' },
          links: 'inherit',
        }),
        attribution: fields.child({ kind: 'inline', placeholder: 'Attribution...' }),
      },
    }),
  },
}),

Other configuration options

The document field has many more configuration options like images, layouts, tables, links or dividers.

Here is a more comprehensive example:

content: fields.document({
  label: 'Content',
  links: true,
  layouts: [[1], [1, 1]],
  images: {
    directory: 'src/content/blog/_images',
    publicPath: '/src/content/blog/_images/',
    schema: {
      title: fields.text({
        label: 'Caption',
        description:
          'The text to display under the image in a caption.',
      }),
    },
  },
  dividers: true,
  formatting: {
    alignment: true,
    blockTypes: true,
    headingLevels: true,
    inlineMarks: {
      code: true,
      bold: true,
      italic: true,
      underline: true,
      strikethrough: true,
    },
    listTypes: true,
  },
  tables: true,
}),

Type signature

For the full reference, you can find the latest version of this field's type signature at: https://docsmill.dev/npm/@keystatic/core@latest#/.fields.document