Document field

⚠️

fields.markdoc has superseded this field. fields.mdx is also available if you prefer MDX.

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...' }),
      },
    }),
  },
}),

You can nest component blocks within each other by using the Child field with the componentBlocks property set to 'inherit':

document: fields.document({
  label: 'Document',
  formatting: true,
  componentBlocks: {
    sectionContainer: component({
      // A preview is needed to show the child field
      preview: ({fields}) => (
        <div style={{ padding: '1rem 0' /* styling is up to you */ }}>
          {fields.children.element}
        </div>
      ),
      label: 'Section Container',
      schema: {
        content: fields.child({
          kind: 'block',
          componentBlocks: 'inherit',
          placeholder: 'Add component blocks here...',
        }),
      },
    }),
  },
}),

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