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.
markdown:
engine: commonmark
options:
table: true
code_block_fences: '```'
{
"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.
Determines which Markdown engine to use while editing in CloudCannon. Supported values are kramdown and commonmark. Defaults to commonmark.
Ensure '/' is added to self-closing HTML tags (e.g. <br />) when saved back to your file.
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.
If true, list items will be saved with an extra trailing newline.
This should be either ~~~ or ```.
If set, this determines which styles for fences to use for code blocks in your Markdown.
Defaults to ```.
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.
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.
If true, tables are saved in Markdown format. If false, tables are 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.
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.
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.
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.
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.
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, andimg: 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 typeright: Markdown attributes are saved directly following the elementspace right: Markdown attributes are saved directly following the element, with a space in-betweenbelow: Markdown attributes are saved after a newlinenewline below: Markdown attributes are saved after two newlinesright-of-prefix: This option only relates to list items (li). Markdown attributes are saved after the list prefix.
For example:
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.
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 front matter 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.
Supported for CommonMark only.
Automatically converts URL-like text to links.
Supported for CommonMark only.
Enables automatic typograhic replacement. For example "(c)" becomes "©", and "..." becomes "…".
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.
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.
This is a single paragraph
with a line break in the middle.
breaks: truemeans that the newline will be preserved as\n.breaks: falseandxhtml: falsemeans that the newline will be changed to<br>.breaks: falseandxhtml: truemeans 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.
markdown:
engine: commonmark
options:
table: true
gfm: true
{
"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:
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:
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:
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