Configuring your Markdown engine

To store and edit Markdown content in CloudCannon, we need to process it into HTML to make it editable. You can use any Markdown engine you want when building your site, this only covers the Markdown content you edit inside CloudCannon.

CloudCannon supports the CommonMark and Kramdown specifications. The implementations for these are markdown-it (JavaScript) andkramdown (Ruby). Both of these support various options that are configurable, with good default options covering most use cases. You can adjust these if you need to precisely match what your SSG uses to process Markdown for your builds.

CommonMark

CommonMark is a popular Markdown specification that aims to become standard and unambiguous.

To use CommonMark for your build and editors:

Add the jekyll-commonmark gem to your Gemfile
Set the markdown field to CommonMark in _config.yml
Set your options in the commonmark field in _config.yml

Gemfile

source 'https://rubygems.org'

gem 'jekyll', '3.8.5'

group :jekyll_plugins do
  gem 'jekyll-commonmark', '1.3.1'
end

_config.yml

markdown: CommonMark

commonmark:
  options: ["SMART", "UNSAFE"]
  extensions: ["strikethrough", "table"]

Note

The UNSAFE option is required for HTML content inside your Markdown files to render correctly.

CommonMark does not support a syntax to define attributes on elements. In order to preserve attributes, that content saves as HTML within your Markdown files.

Goldmark is the default Markdown engine for Hugo. CloudCannon uses markdown-it to process Markdown for the editors. The settings you set for Goldmark are automatically mapped across to markdown-it.

See the Hugo Documentation for information on how to configure Goldmark. Other engines set with defaultMarkdownHandler are not officially supported.

Note

The UNSAFE option is required for HTML content inside your Markdown files to render correctly.

markdown-it is the default Markdown processor for Eleventy.

The default configuration is { html: true } to match the Eleventy default, but you can update this to match your site by setting the markdownItOptions option for eleventy-plugin-cloudcannon:

.eleventy.js

module.exports = function (eleventyConfig) {
  eleventyConfig.cloudcannonOptions = {
    markdownItOptions: {
      html: true,
      linkify: true
    }
  };
};

If you are managing the eleventy-plugin-cloudcannon plugin manually, pass the options directly:

.eleventy.js

const pluginCloudCannon = require('eleventy-plugin-cloudcannon');

module.exports = function (eleventyConfig) {
  eleventyConfig.addPlugin(pluginCloudCannon, {
    markdownItOptions: {
      html: true,
      linkify: true
    }
  });
};

markdown-it is the default Markdown processor in CloudCannon.

The default configuration is { html: true } to allow the images with width and height attributes the Rich Text editors create, but you can update this to match your site by setting the generator.metadata in your cloudcannon.config.* file:

cloudcannon.config.cjs

module.exports = {
  generator: {
    metadata: {
      markdown: 'markdown-it',
      'markdown-it': {
        html: true,
        linkify: true
      }
    }
  }
};

Kramdown

Kramdown is another specification, and the default Markdown processor for Jekyll.

Jekyll comes standard with Kramdown installed and configured. CloudCannon reads your kramdown settings in _config.yml to match editing and builds.

To use Kramdown: