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:
- GitHub Repository
- Sitecore Marketplace
- Markdown For Sitecore - Which Mode Should You Use?
- Markdown For Sitecore - Authoring Guide
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
<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:
- Markdown For Site Authoring Guide
- PHP Markdown Extra (Markdown for Sitecore does not support special attributes - yet)
- Markdown Syntax
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!
