With Mango, posts and pages are stored in simple text files. For each of these
Document instance is created, with various useful attributes such as
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
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.
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.
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]. : 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.
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
...is replaced by … (an ellipsis)
foo -- baris rendered as foo — bar
Replacements are not made within code snippets. There is no way to escape
these replacements – set
False if you find them