Markdown For Sitecore: Which Mode Should I Use?

Looking to implement Markdown for Sitecore in your project?

• Markdown for Sitecore - Module
• Markdown for Sitecore - Authoring Guide
• GitHub Repository

Markdown for Sitecore has 4 modes. The mode you decide to use depends largely on who your content author is and what you'd like them to do. Modes are configured at the as the fields source at the template level in query string format.

Mode	Standard Markdown	Enhanced Markdown	HTML	Source
Safe Mode	X			safemode=1&extramode=0
Extra Mode	X	X	X	safemode=0&extramode=1
Mixed Mode	X	X		safemode=1&extramode=1
Default Mode	X		X	safemode=0&extramode=0

See the source being set for this post.

Safe Mode

Safe Mode is best suited for a simplified & protected authoring experiencing. Authors have traditional Markdown features available for use but cannot author structural HTML. div and span tags will escaped and only a select whitelisted HTML tags will be permitted.

Whitelisted Tags:

Extra Mode

Extra Mode is for very powerful, HTML-savy users. It enhances traditional Markdown with some features from Markdown Extra like tables, definition lists & footnotes among others (but not special attributes, yet). The ability to mix HTML with Markdown allow the author use which ever is best-fit and accommodate edge-cases.

FYI - all of Fishtank's new blog posts are written in Extra Mode.

Mixed Mode

Mixed Mode is best-fit for authoring inside of a well structured site. It puts content first instead of HTML and formatting. Because it uses SafeMode it takes HTML out of the equation. Its use of ExtraMode gives additional functionality to the user. Although it may seem counter-intuitive, (IMHO) the lack of HTML is liberating to the authoring experience.

Default Mode

Default Mode provides allows for standard Markdown and HTML. Given that it allows HTML but does support the enhanced Markdown features of ExtraMode this feels like the odd setting out. I don't know of any, but if authors find issues in ExtraMode consider downgrading to Default Mode.

Styling

A quick thought on styling. My preferred pattern is wrap the <sc:RenderField Field="MarkdownContent" runat="server /> at some parent-level in a decorator class.

 
<div class="markdown-post">
  <sc:RenderField Field="MarkdownContent" runat="server />
</div>

And setup the stylesheet (preferably SASS or LESS) as follows:

 
.markdown-post {}
.markdown-post p {...}
.markdown-post h1 {...}
.markdown-post a {...}
.markdown-post em {...}
.markdown-post strong {...}
.markdown-post table {...}
.markdown-post table td {...}

Other Thoughts

Because each Mode is configured in the Source field, each template can use a mode best-fit for it. I would use SafeMode for content like news releases, content blocks or feature wells. For general page content MixedMode is a good fit. Because I'm a "power user" I like using ExtraMode for blog posts - it gives me a good balance of structure and freedom.

Which ever mode works for you, it's a nice change of pace from authoring HTML. Thanks for reading!