Configure your Markdown engine

Last modified: October 9th, 2024

CloudCannon needs to parse Markdown content into HTML to preview and edit it. Additionally, CloudCannon needs to save your Markdown in a format recognized by your SSG to build your content.

You can use the top-level markdown key in your global configuration file to define how CloudCannon should parse and save your Markdown content.

cloudcannon.config.yaml
copied
markdown:
  engine: commonmark
  options:
    table: true
    code_block_fences: '```'
cloudcannon.config.json
copied
{
  "markdown": {
    "engine": "commonmark",
    "options": {
      "table": true,
      "code_block_fences": "```"
    }
  }
}

CloudCannon supports CommonMark and Kramdown using markdown-it (JavaScript) and kramdown (Ruby). You can use any Markdown engine you want when building your site. This article only concerns the way CloudCannon parses and saves your Markdown while you're editing.

engine - string#

Determines which Markdown engine to use while editing in CloudCannon. Supported values are kramdown and commonmark. Defaults to commonmark.

options.xhtml - boolean#

Ensure '/' is added to self-closing HTML tags (e.g. <br />) when saved back to your file.

options.breaks - boolean#

This key allows you to configure how the Visual Editor renders newline characters. You can use this key to match the Visual Editor's behavior to your SSG's Markdown engine.

If true, CloudCannon will render newline characters within paragraphs as <br> tags in the Visual Editor. CloudCannon will also change all <br> tags in the file into newline characters before saving to preserve your original formatting.

If false, CloudCannon will render newline characters within paragraphs normally when converted to HTML in the Visual Editor (i.e., collapsed by default). You can use Shift + Enter to add a linebreak within a paragraph. CloudCannon will save this as a <br> to ensure the linebreak appears when the site is built.

In Kramdown, this option will only work if options.gfm is also enabled.

options.spaced_lists - boolean#

If true, list items will be saved with an extra trailing newline.

options.code_block_fences - string#

This should be either ~~~ or ```. If set, this determines which styles for fences to use for code blocks in your Markdown.

Defaults to ```.

options.treat_indentation_as_code - boolean#

Supported for CommonMark only. In Kramdown, this behaviour is always enabled.

If true, text indented with 4 spaces will be treated as a code block.

Most Jekyll and Hugo sites will want to set this to true.

options.escape_snippets_in_code_blocks - boolean#

If true, snippets inside code blocks will be always rendered as plain text instead of editable elements.

This behavior is always on when editing MDX files.

options.table - boolean#

If true, tables are saved in Markdown format, instead of being converted to HTML.

Enable this option only if your SSG's Markdown engine recognizes this syntax.

Most Jekyll sites will want to set this to true.

options.strikethrough - boolean#

If true, strikethrough elements (<del>, <s>, <strike>) are wrapped with double tildes (e.g. ~~example~~), instead of being output as HTML.

Enable this option only if your SSG's Markdown engine recognizes this syntax.

options.subscript - boolean#

If true, subscript elements (<sub>) are wrapped with tildes (e.g. ~example~), instead of being output as HTML.

Enable this option only if your SSG's Markdown engine recognizes this syntax.

options.superscript - boolean#

If true, subscript elements (<sup>) are wrapped with carets (e.g. ^example^), instead of being output as HTML.

Enable this option only if your SSG's Markdown engine recognizes this syntax.

options.attributes - boolean#

If true, HTML attributes will be saved in Markdown format. Otherwise, elements with attributes may be converted to HTML to preserve the attributes.

Enable this option only if your SSG's Markdown engine recognizes this syntax.

options.attributes - boolean#

If true, HTML attributes will be saved in Markdown format. Otherwise, elements with attributes may be converted to HTML to preserve the attributes.

Enable this option only if your SSG's Markdown engine recognizes this syntax.

options.attributes_elements - object#

This key determines how to save Markdown format attributes for different elements. For example, different SSGs may require Markdown attributes to appear on a newline for paragraphs, but on the same line for images.In most cases you should not need to set this option.

Allowed keys are:

  • p, h1, h2, h3, h4, h5, h6, hr, ul, ol, li, table, blockquote, and img: These specify how to save Markdown attributes for specific HTML elements.
  • inline: specifies how to save "inline" HTML elements, when not overridden by a more specific key.
  • block: specifies how to save "block" HTML elements, when not overridden by a more specific key.

Allowed values are:

  • none: don't allow Markdown attributes to be saved on this element type
  • right: Markdown attributes are saved directly following the element
  • space right: Markdown attributes are saved directly following the element, with a space in-between
  • below: Markdown attributes are saved after a newline
  • newline below: Markdown attributes are saved after two newlines
  • right-of-prefix: This option only relates to list items (li). Markdown attributes are saved after the list prefix.

For example:

example.md
copied
This example shows how different options would impact attributes on list items.

* None
* Right{.red}
* Space Right {.red}
* Below
{.red}
* Space Below

{.red}
* {.red} Right of prefix

Read the section below to learn more about how to configure this, and the default values for different SSGs.

options.gfm - boolean#

Enables extra parsing options consistent with GitHub Flavored Markdown.

Defaults to true.

Display-only options#

Display-only Markdown options in markdown.options can transform your content to render displays but cannot affect the saved content in your files.

Display-only options facilitate visual data previews in the Visual Editor, comments on inputs, and descriptions for collections.

If your site uses visual data previews to enable live editing from your rich text frontmatter fields, CloudCannon will use all the above options when parsing your Markdown and passing it into the Visual Editor.

CloudCannon does not automatically communicate your Markdown settings with any third-party libraries you might use to render visual data previews within the editor. If those libraries need to reparse your Markdown and do not also read your Markdown settings, they may inconsistently render some content in the previews.

options.linkify - boolean#

Supported for CommonMark only.

Automatically converts URL-like text to links.

options.typographer - boolean#

Supported for CommonMark only.

Enables automatic typograhic replacement. For example "(c)" becomes "©", and "..." becomes "…".

options.quotes - string#

Supported for CommonMark only.

This should be a string with 4 characters, representing (in order) your desired opening double quote, closing double quote, opening single quote, and closing single quote characters. Normal quote characters will be replaced with these when rendered.

For example, „“‚‘.

This option will only work if typographer is also enabled.

options.heading_ids - boolean#

Supported for CommonMark only.

If true, headings within your Markdown will automatically be given ID attributes. Since heading_ids is a display-only option, this is only relevant for previews if your site implements special behavior for headings with IDs (e.g. an on-hover style).

Configuring line breaks#

If your SSG requires a particular format of line break within paragraphs, you can use the breaks and xhtml options to configure this.

about.md
copied
This is a single paragraph
with a line break in the middle.
  • breaks: true means that the newline will be preserved as \n.
  • breaks: false and xhtml: false means that the newline will be changed to <br>.
  • breaks: false and xhtml: true means that the newline will be changed to <br />.

Constraints on Markdown tables#

The GitHub Flavored Markdown (GFM) specification allows tables to be rendered in Markdown format, but requires all tables to have exactly one header row (Kramdown's implementation of GFM is an exception to this).

If you have configured CloudCannon to use GFM and to render tables as Markdown, CloudCannon will automatically add a header row when you add a table in the rich text editor. Controls for removing this header row will be disabled.

cloudcannon.config.yaml
copied
markdown:
  engine: commonmark
  options:
    table: true
    gfm: true
cloudcannon.config.json
copied
{
  "markdown": {
    "engine": "commonmark",
    "options": {
      "table": true,
      "gfm": true
    }
  }
}

With this configuration, tables will be rendered as HTML if they violate this constraint, to preserve your content.

Default element attribute options#

CloudCannon uses sensible defaults for markdown.options.attributes_elements based on the configured engine.

If your markdown.engine is kramdown, markdown.options.attributes_elements will default to:

cloudcannon.config.yml
copied
markdown:
  options:
    attributes_elements:
      inline: right
      block: below
      li: right-of-prefix

If your markdown.engine is commonmark, markdown.options.attributes_elements will default to:

cloudcannon.config.yml
copied
markdown:
  options:
    attributes_elements:
      inline: none
      block: space right
      img: right
      ul: below
      ol: below
      li: space right
      table: newline below
      blockquote: below

Hugo sites use Goldmark for Markdown processing, which has different behavior to other CommonMark parsers.

If you encounter issues with Markdown format attributes on Hugo sites, we recommend the following configuration:

cloudcannon.config.yml
copied
markdown:
  engine: 'commonmark'
  options:
    attributes: true
    attributes_elements:
      inline: none
      block: space right
      ul: below
      ol: below
      blockquote: below
      p: below
      img: below
      hr: below
      table: below
      li: none

Open in a new tab