Markdown

Markdown’s easy-to-write, easy-to-read format is useful and popular for writing on the web.

Why?

Harp includes the common, useful preprocessors by default. This means you don’t have to waste time converting your Markdown into HTML — everything just works. Plus, Jade and EJS files can import Markdown files as partials, allowing you to effectively re-use your writing.

Usage

Harp’s asset pipeline is easy to use. All preprocessing happens implicitly, so there is nothing to set up. Just name your file with an .md extension, and the Harp web server will serve it as .html.

Some implementations of Markdown also accept .markdown, .mdown, or .txt extensions. Harp only preprocesses .md files.

Example

This project contains an index.md and an about.md in the served directory.

mysite/
  |- index.md
  `- about.md

Both index.md and about.md are served as HTML. Requests to the following paths will all work:

/
/index
/index.html
/about
/about.html

Compiling the project (harp ./mysite ./www) will export the same pages as index.html and about.html to the build directory.

GitHub Flavoured Markdown

Harp supports the supplementary GitHub Flavoured Markdown syntax. (This doesn’t include the GitHub-specific features like Task Lists or @mentions.) That gives you fenced code blocks:

```
function test() {
  console.log("Hello, world");
}
```

You may also specify the language:

```javascript
function test() {
  console.log("Hello, world");
}
```

function test() {
  console.log("Hello, world");
}

Harp will serve the code block as HTML:

<pre><code class="language-javascript">function test() {
  console.log(&quot;Hello, world&quot;);
}</code></pre>

The language- class name follows the W3C and WHATWG convention for specifying the type of code, which means client-side highlighters like Prism work out of the box.

Markdown is not a template engine

Markdown is rendered to static HTML by marked. It doesn’t execute template code, so the following don’t work inside the body of a .md file:

<%= variable %> and <%- variable %> interpolation
partial() calls
<% if (...) %> and <% for (...) %> blocks

The values from a _data.json entry or _harp.json globals are attached to the page’s render context — they’re just not visible inside the markdown body, because the markdown processor doesn’t reach for them.

In practice, this is fine: the surrounding _layout.ejs (which is a real EJS template) can read those variables and use them for the <title> tag, navigation, related-post lists, and any other chrome. The .md file itself stays pure prose. If you need template logic inside the body of a page, write it as .ejs instead.

Managing file extensions

You may want to create a markup file other than .html using Markdown. Just prefix .md with the desired extension. For example, feed.xml.md is served as feed.xml.

This trick is also possible (and often more useful) with EJS and Jade.