How to use markdown on your websites

Markdown logo

An excellent way to pre-render (aka convert) markdown to html at build-time on your websites is to use pandoc. If you have pandoc installed on your machine it is as simple as using, without any indenting, @system{inject}("pandoc file-path") where file-path is the path to the markdown file you want converted.

For more information on using Pandoc, like converting from and to other markup languages, check out the Pandoc User's Guide.

Note: changes to the markdown file will not be recognised by build-updated unless you manually add it as a user-defined page dependency. See the Nift commands page for how to manually add user-defined page dependencies.

Options for converting markdown to html at load-time on your websites include:

The Nift documentation covers using markdown on your websites using Showdown, for a basic example see the template markdown-site. To use Showdown on your websites you will need showdown.js or showdown.min.js (you can get v1.9.0 from here) along with process_md_blocks.js script.

To use the Showdown add includes for the above scripts along with Showdown scripts to the end of your \. For example a page.template file might be:

<!DOCTYPE html>
		<title>site title - @[title]</title>

		<script src='@pathtofile{!p}(site/js/process_md_blocks.js)'></script>
		<script src="@pathtofile{!p}(site/js/showdown.min.js)"></script>
			var converter = new showdown.Converter();
			converter.setOption('tables', 'on');
			converter.setOption('strikethrough', 'on');
			converter.setOption('emoji', 'on');
			elements = document.getElementsByClassName('markdown');
			for(var i=0; i<elements.length; i++)
				elements[i].innerHTML = converter.makeHtml(elements[i].innerHTML.replace(/&lt;/g, "xwxw").replace(/&gt;/g, "pqpq")).replace(/xwxw/g, "&lt;").replace(/pqpq/g, "&gt;");

It's also handy to add the following bit of css to one of your css files to hide visibility of textareas when pages are loading:

	visibility: hidden;

	visibility: hidden;

You can then do a block of markdown as follows:

<textarea class="markdown">
	markdown code here

Examples of using markdown

| Tables        | Are           | Cool  |
| ------------- |:-------------:| -----:|
| **col 3 is**  | right-aligned | $1600 |
| col 2 is      | *centered*    |   $12 |
| zebra stripes | ~~are neat~~  |    $1 |