Module: Markdown for Sitecore

The Easiest Way To Author Content In Sitecore

Introducing Markdown for Sitecore

The goal of Markdown for Sitecore is to provides user with an elegant, expressive, lightning-fast alternative for content creation.

  • Built specifically for writing on the web
  • Fastest way to author content
  • Simpler than rich-text
  • More expressive that plain text
  • Remove HTML from authoring experience (but still get HTML output)
  • Mix Markdown & HTML for advanced authors

Markdown is a writing format (not a publishing format like HTML and XML). If you're new to Markdown this is the best place to start.

It turns this quickly-typed, easy to read content from this:

 
Significant Events In History
=========

History is full of signification events.  It's doubtful that Markdown for Sitecore will be historically significant but hopefully it's useful to the Sitecore community.

* The _first_ item in a lists
* One before the third item
* Finally the 3rd item

Obligatory link to (Sitecore)[http://www.sitecore.net] before we show tables.

Cools Things About Sitecore
---------

Feature | True or False
----------|----------------
marketer-friendly | true
developer-friendly | true
ContentSearch API | true

> Markdown for Sitecore is handy.
> - Anonymous

To this:

 
<h1 id="significant-events-in-history">Significant Events In History</h1>

<p>History is full of signification events. It’s doubtful that Markdown for Sitecore will be historically significant but hopefully it's useful to the Sitecore community.</p>

<ul>
	<li>The <em>first</em> item in a lists</li>
	<li>One before the third item</li>
	<li>Finally the 3rd item</li>
</ul>

<p>Obligatory link to <a href="http://www.sitecore.net">Sitecore</a> before we show tables.</p>

<h2 id="cools-things-about-sitecore">Cools Things About Sitecore</h2>

<table>
	<thead>
		<tr>
		<th align="left">Feature</th>
		<th align="left">True or False</th>
		</tr>
	</thead>
	<tbody>
		<tr class="odd">
			<td align="left">marketer-friendly</td>
			<td align="left">true</td>
		</tr>
		<tr>
			<td align="left">developer-friendly</td>
			<td align="left">true</td>
		</tr>
		<tr>
			<td align="left">ContentSearch API</td>
			<td align="left">true</td>
		</tr>
	</tbody>
</table>

<blockquote>
	<p>Markdown for Sitecore is handy. - Anonymous</p>
</blockquote>

How To Use

Getting started:

When the installation is complete select the Markdown field type in your template. Use the Source attribute of the field located in the items template to configure. This way, your attributes are applied using <sc:RenderField /> and when indexed/accessed via the ContentSearch API.

Configurable attributes are all have corresponding 1 (true) or 0 (false) values:

Attribute Description
safemode Allow a whitelisted common HTML tags to be used in authoring
extramode Allow advanced Markdown authoring for tables, definition lists, fenced code blocks, footnotes, abbreviations & markdown inside of html
markdowninhtml Allows Markdown syntax to be used inside of HTML elements*
autoheadingids Headings are assigned IDs based on their text using the Pandoc algorithm*
newwindowforexternallinks External links are assigned target="_blank"
newwindowforlocallinks Site links are assigned target="_blank"
nofollowlinks Adds a rel="nofollow" to links
htmlclassfootnotes CSS class applied to footnotes*
htmlclasstitledimages CSS class applied to title images*

(*) = with extramode enabled

The most frequently used options are safemode & extramode. By mixing these Markdown for Sitecore can run in a variety of modes. Options are declared in a query string format:

 
// The settings used for this blog post!
safemode=0&extramode=1&markdowninhtml=0

// Markdown only please, safemode=1 is great to constrain content authoring
safemode=1&extramode=1&markdowninhtml=0&htmlclassfootnotes=footnote-class

Use it in a page like any other field:

 
<sc:renderField FieldName="YourMarkdownField" runat="server" />

OOTB the Fishtank.Markdown.config adds a line to so Markdown fields are handled by the ContentSearch API as well.

 
<contentSearch>
  <configuration>
	<defaultIndexConfiguration>
	  <fieldReaders>
		<mapFieldByTypeName>
		  <fieldReader fieldTypeName="markdown" fieldReaderType="Fishtank.CustomFields.Markdown.FieldReaders.MarkdownFieldReader, Fishtank.CustomFields.Markdown" />
		</mapFieldByTypeName>
	  </fieldReaders>
	</defaultIndexConfiguration>
  </configuration>
</contentSearch>

Markdown Syntax

Markdown for Sitecore is built on top of MarkdownDeep. For syntax on how to author Markdown content I'd recommend:

Quick & Easy Installation

To get up and running quickly download and install package for your Sitecore version below. Select merge/merge if prompted during install.

Each Sitecore package contains:

Type Location
Item core:///sitecore/system/Field types/Custom Types
Item core://sitecore/system/Field types/Custom Types/Markdown
Config /App_Config/Include/Fishtank.Markdown.config
DLL /bin/Fisthank.CustomFields.Markdown.dll

Advanced Installation

To build your own version of Markdown for Sitecore and integrate into Visual Studio solution, you can find it's GitHub repo here as well as the Sitecore 7 and Sitecore 6 versions respectively.

Here is a high-level overview of the steps to integrate it into your solution:

  • Install the sitecore package
  • Add the project to your existing solution
  • Add appropriate Sitecore references (Sitecore.Kernel.dll, Sitecore.ContentSearch) to the project
  • Add the Fishtank.Markdown.config to your /App_Config/Include

Troubleshooting

  • Markdown for Sitecore 7 is built for the .NET 4.5 framework
  • Markdown for Sitecore 6 is built for the .NET 4.0 framework

When doing an advanced installation please check the following:

  • If NuGet cannot load MarkdownDeep library, please right-click your solution node in Visual Studio, click Enable NuGet Package Restore. Once you have the package you may disable this functionality and commit MarkdownDeep to source control.
  • Fishtank.CustomFields.Markdown has been added a copy-local reference to your primary Sitecore project.
  • References to your local Sitecore.Kernel.dll (and Sitecore.ContentSearch.dll if using Sitecore 7) have been added to the Fishtank.CustomFields.Markdown project.
  • The Fishtank.CustomFields.Markdown project has the same .NET target version as the rest of your solution (right-click project > properties > application tab > target framework)

What's Next?

We'd love to know what you think. We created this to support the Sitecore community so we welcome your input. If you use this module please drop us a line in the comments.

Also find Markdown for Sitecore in the Sitecore Marketplace.

Enjoy!

Fish