Syntax (for writing posts)

With Mango, posts and pages are stored in simple text files. For each of these files a Document instance is created, with various useful attributes such as title and html. Mango's syntax — a superset of Markdown's syntax — makes it possible to include metadata in Markdown documents simply and elegantly.

When writing documents (posts and/or pages) one has access to the complete Markdown syntax. Furthermore, Markdown extensions can be activated via the MARKDOWN_EXTENSIONS setting (by default, the Definition Lists extension and Fenced Code Blocks extension are active).

The extension that Mango can't live without is the Meta-Data extension. This allows post metadata to be stored at the top of the text file:

date: 19 June 2010
time: 12:25am
tags: blogging, Mango, syntax

Writing posts
=============

With Mango, posts and pages are stored in simple text files...

Mango extracts a post's metadata and makes them accessible to the relevant templates. Not only does this approach obviate the need for a database, but it establishes a straightforward connection between the Markdown source and the rendered content which makes publishing content with Mango seem effortless.

Mango adds a sprinkling of its own syntax. The two most significant additions accommodate excerpts and updates.

Excerpts

Templates often require post excerpts. An index template, for example, may display excerpts for the three most recent posts. Mango provides an elegant way to specify excerpts:

author: William Shakespeare
year: 1601

Here the anthem doth commence:—
Love and constancy is dead;
Phoenix and the turtle fled
In a mutual flame from hence.

The Phoenix and the Turtle
==========================

The Phoenix and the Turtle
Let the bird of loudest lay...

For meaty posts, a hand-crafted summary is sometimes required. The above format handles these situations nicely (make friends with your text editor's keyboard shortcut for block editing to quickly add those pipes).

In many cases, though, the first paragraph or two provide a good introduction. Copying and pasting an excerpt would violate the DRY principle! Correct, and that's bad!

An excerpt can also be specified within the post's body:

author: William Shakespeare
year: 1601

The Phoenix and the Turtle
==========================

The Phoenix and the Turtle
Let the bird of loudest lay...

And thou, treble-dated crow,
That thy sable gender mak'st
With the breath thou giv'st and tak'st,
'Mongst our mourners shalt thou go.

* * * * * * * * * * * * * * * * * * * *

Here the anthem doth commence:—
Love and constancy is dead;
Phoenix and the turtle fled
In a mutual flame from hence.

* * * * * * * * * * * * * * * * * * * *

So they loved, as love in twain
Had the essence but in one;
Two distincts, division none;
Number there in love was slain.

Hearts remote, yet not asunder;
Distance, and no space was seen...

The pipes are stripped before the post's body is converted from Markdown to HTML. Note that it's possible to demarcate more than one portion of a post's body in this way; the demarcated portions are concatenated to form the excerpt.

Updates

Posts dealing with changeable subjects sometimes need to be updated to stay relevant. Even a post that primarily conveys its author's opinions may require amending. One of the wonderful things about creating content for the Web is that oversights can easily be corrected.

Unfortunately, not all blogging software acknowledges the fact that publishing a post is not like publishing a book. Mango does.

Adding an update to a post is easy:

* * * * * * * * * * * * * * * * * * * * * * * * * * *

Update: 21 September 2009, 11:53am (Pacific/Auckland)

I neglected to mention that this code also requires
[script.aculo.us][1].

[1]: http://script.aculo.us/

* * * * * * * * * * * * * * * * * * * * * * * * * * *

By default, this will generate the following HTML:

<div class="update">
  <h4>Update — <time datetime="2009-09-20T23:53+00:00">20 September 2009</time></h4>
  <p>I neglected to mention that this code also requires <a href="http://script.aculo.us/">script.aculo.us</a>.</p>
</div>

Think of an update as a post within a post – it can have its own metadata (date and time are useful here!) and can contain its own links, code blocks, etc.

Replacements

When REPLACEMENTS is True, Mango performs a couple of replacements which allow Markdown files to be kept free of characters that look ridiculous in monospaced fonts. It also means that you can use ellipses and em dashes without opening your character palette or memorizing arcane keyboard sequences.

... is replaced by … (an ellipsis)
foo -- bar is rendered as foo — bar

Replacements are not made within code snippets. There is no way to escape these replacements – set REPLACEMENTS to False if you find them annoying.