Configure Markdown syntax preferences in the Static Site Editor
Problem to solve
Markdown is a flexible syntax, with multiple ways to achieve the same rendered output. Writers familiar with Markdown often develop strong preferences for syntax (using
* instead of
- for list items, for example). Further complicating things, there are many flavors of Markdown (CommonMark, Kramdown, MultiMarkdown) that extend the base syntax in various ways.
A static site generator will typically implement a Markdown parser that can interpret the selected Markdown flavor and reliably output the proper HTML. However as we look to introduce a rich text, WYSIWYG editing experience into the process, the flexibility of Markdown can become a liability.
The process of loading the Markdown content into the WYSIWYG editor requires converting the content into HTML. After editing the content, we need to write the file back out as Markdown so the static site generator can do its job. If you do not write Markdown in the specific stylistic preferences defined in the Markdown -> HTML converter, the resulting output will not match the original source.
A source file is formatted like this (valid Markdown)
# Hello world This is my static site. * List item 1 * List item 2 * List item 3
The page is loaded into the WYSIWYG editor and converted to
<h1>Hello world</h1> <p>This is my static site.</p> <ul> <li>List item 1</li> <li>List item 2</li> <li>List item 3</li> </ul>
But because the Markdown parser in the Static Site Editor is configured to use
- for list items, when the file is published back out, the resulting Markdown looks like
# Hello world This is my static site. - List item 1 - List item 2 - List item 3
Eventually we'd like to ignore extraneous formatting changes. But there's also a valid use case for intentionally applying consistent Markdown. While some contributors may balk at the idea of their stylistic preferences being overridden, there are times and projects for which that is actually desirable.
We should allow users to easily configure the Markdown syntax preferences in the Static Site Editor. This will allow those with strong preferences for specific Markdown syntax options to continue working in the way they are most familiar. It will also help when using the Static Site Editor with a project that may have a large amount of existing content that doesn't conform to the default settings defined in the parser.