Working with a specific static site generator?
Customize CloudCannon's documentation to suit your SSG.
Great! We'll show you documentation relevant to .
You can change this any time using the dropdown in the navigation bar.
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": "```"
}
}
}module.exports = {
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.
specific doc
CloudCannon automatically reads your settings from _config.yml to match the Markdown formatting of your SSG.
specific doc
CloudCannon automatically reads your Goldmark settings from Hugo to match the Markdown formatting of your SSG.
Determines which Markdown engine to use while editing in CloudCannon. Supported values are kramdown and commonmark.
specific doc
Defaults to kramdown when using Jekyll.
specific doc
Defaults to commonmark.
Ensure '/' is added to self-closing HTML tags (e.g. <br />) when saved back to your file.
If true, newlines within paragraphs will be rendered as linebreaks (<br>) in the Visual Editor. If false, these newlines will appear as single whitespace characters.
If true, CloudCannon will change all <br> tags in the file back into newline characters before saving, to preserve your original formatting. If your file already contained <br> tags, these will also be converted.
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.
specific doc
Defaults 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, instead of being converted to HTML.
Enable this option only if your SSG's Markdown engine recognizes this syntax.
specific doc
Defaults to true for Jekyll.
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.
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.
This key determines how to save Markdown format attributes for inline elements.
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 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.
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: falsemeans that the newline will be preserved as\n.breaks: trueandxhtml: falsemeans that the newline will be changed to<br>.breaks: trueandxhtml: 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
}
}
}module.exports = {
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 your SSG. You should only override these if you're using an SSG that requires a different syntax for Markdown attributes than these defaults.
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
specific doc
If your markdown.engine is commonmark and you're using Hugo, markdown.options.attributes_elements will default to:
markdown:
options:
attributes_elements:
inline: none
block: space right
ul: below
ol: below
blockquote: below
p: below
img: below
hr: below
table: below
li: none
CloudCannon gives different defaults for Hugo to account for differences in syntax between Goldmark and other CommonMark parsers.
specific doc
If your markdown.engine is commonmark (and you're not using Hugo), 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