Apostate Café


By Joshua Ellis

Pubished:

Posted in: meaning-beauty-whimsy
Tagged as: Calepin / Markdown / reStructuredText

Working with Calepin in Markdown and reStructuredText

Working with Calepin in Markdown and reStructuredText

Calepin {: #calepin }

Calepin is a publishing platform based on text files and Dropbox. Calepin is powered by Pelican, a static weblog generator written in Python. Pelican uses the Python Markdown library and the reStructuredText parser from Docutils to produce static HTML files.

Most of this page is a rehash of existing docs for Markdown, from the Python Mardown module documentation, from the Pelican source, and from the reStructuredText documentation, along with pieces from

Using Markdown {: #markdown }

Calepin is based on Pelican, which uses the Python Markdown package with the extra and codehilite extensions. From the original Markdown documentation:

Markdown is not a replacement for HTML, or even close to it. Its syntax is very small… The idea for Markdown is to make it easy to read, write, and edit prose. HTML is a publishing format; Markdown is a writing format. Thus, Markdown’s formatting syntax only addresses issues that can be conveyed in plain text. For any markup that is not covered by Markdown’s syntax, you simply use HTML itself.

Paragraphs {: #paragraphs }

Paragraphs are created by lines of text. Paragraphs are separated with blank lines. One of the things that makes Markdown so useful as a writing format is that it doesn’t care about hard-wrapped text blocks.

For example:

This is the
first paragraph.

This is the
second paragraph.

Produces:

<p>This is the first paragraph.</p>
<p>This is the second paragraph.</p>

Special Characters {: #specials }

Markdown features intelligent handling of & ampersand, < less-than, and > greater-than symbols in text. It understands the difference between an unadorned &, one in text (e.g. this&that), and one in embedded HTML (e.g. &copy; becomes ©). Similarly < and > are fine in Markdown text, and interpreted properly when used as embedded HTML. For example:

<del>this is strikethrough</del>

Renders properly as this is strikethrough.

Headers {: #headers }

Headers, those <h1> <h2> <h3> <h4> <h5> <h6> tags, can be declared two ways in Markdown. Headers can be “underlined” with = (first-level) and - (second-level), like this:

This is h1
==========

This is h2
----------

Which becomes

<h1>This is h1</h1>
<h2>This is h2</h2>

Or headers can be declared with octothorps, like this:

# The First
## The Second
### The Third

Which becomes

<h1>The First</h1>
<h2>The Second</h2>
<h3>The Third</h3>

Blockquotes {: #blockquotes }

> Email-style angle brackets
> are used for blockquotes.

> > And, they can be nested.

> #### Headers in blockquotes
>
> * You can quote a list.
> * Etc.

Email-style angle brackets are used for blockquotes.

And, they can be nested.

Headers in blockquotes

  • You can quote a list.
  • Etc.

Lists {: #lists }

To create an unnumbered list in Markdown, use dash -, asterisk *, or plus + bulllets like this:

- Red
- Green
* Blue
* Yellow
+ Orange
+ Silver
  • Red
  • Green
  • Blue
  • Yellow
  • Orange
  • Silver

Numbered list:

1. Eddie
2. Cantor
  1. Eddie
  2. Cantor

Markdown is pretty smart about getting at what you intend, and allows nested lists.

  1. alpha
  2. beta
    1. gamma
    2. delta
      • epsilon
      • zeta
      • eta
    3. theta
      • iota
      • kappa
        • Bar
      • lambda
      • mu
        • nu
          • xi
            1. omicron
              1. pi
            2. rho
    4. sigma
      • tau
        • upsilon
  3. phi
  4. chi
    1. psi
      1. omega

Which you’d get from:

1. alpha
2. beta
    1. gamma
    2. delta
        - epsilon
        - zeta
        - eta
    3. theta
        - iota
        - kappa
            * Bar
        1. lambda
        2. mu
            - nu
                * xi
                    1. omicron
                        1. pi
                    2. rho
    2. sigma
        * tau
            - upsilon
3. phi
4. chi
    1. psi
        1. omega

Code Blocks {: #code }

SheBang (with path) {: #shebang }

If the first line of the codeblock contains a shebang, the language is derived from that and line numbers are used. If the first line contains a shebang, but the shebang line does not contain a path (a single / or even a space), then that line is removed from the code block before processing. Line numbers are used.

#!/usr/bin/python
# Code goes here ...

Versus

#!python
#!python
# Code goes here ...
Colons {: #colon }

If the first line begins with three or more colons, the text following the colons identifies the language. The first line is removed from the code block before processing and line numbers are not used.

\:::python
:::python
# Code goes here ...

Inline Code {: #inlinecode }

To include code inline with text surround it with backticks ` like this:

Text with `<code>` inside

Which is rendered

<p>e.g. Text with <code>&lt;code&gt;</code> inside</p>

e.g. Text with <code> inside

Horizontal Rules {: #hrs }

You can produce a horizontal rule (<hr />) with three or more hyphens, asterisks, or underscores on a line by themselves. If you use spaces between the hyphens or asterisks. Each of the following lines will produce a horizontal rule:

* * *

***

*****

- - -

---------------------------------------





Linking {: #linking }

This is taken directly from the original Markdown documentation.

Markdown supports two style of links: inline and reference.

In both styles, the link text is delimited by [square brackets].

To create an inline link, use a set of regular parentheses immediately after the link text’s closing square bracket. Inside the parentheses, put the URL where you want the link to point, along with an optional title for the link, surrounded in quotes. For example:

This is [an example](http://example.com/ "Title") inline link.

[This link](http://example.net/) has no title attribute.

Will produce:

<p>This is <a href="http://example.com/" title="Title">
an example</a> inline link.</p>

<p><a href="http://example.net/">This link</a> has no
title attribute.</p>

This is an example inline link.

This link has no title attribute.

If you’re referring to a local resource on the same server, you can use relative paths:

See my [About](/about/) page for details.

Reference-style links use a second set of square brackets, inside which you place a label of your choosing to identify the link:

This is [an example][id] reference-style link.

You can optionally use a space to separate the sets of brackets:

This is [an example] [id] reference-style link.

Then, anywhere in the document, you define your link label like this, on a line by itself:

[id]: http://example.com/  "Optional Title Here"

That is:

  • Square brackets containing the link identifier (optionally indented from the left margin using up to three spaces);
  • followed by a colon;
  • followed by one or more spaces (or tabs);
  • followed by the URL for the link (optionally surrounded by angle brackets);
  • optionally followed by a title attribute for the link, enclosed in double or single quotes, or enclosed in parentheses.

Note that you can put the title attribute on the next line and use extra spaces or tabs for padding, which tends to look better with longer URLs:

[foo]: http://example.com/  "Optional Title Here"
[foo]: http://example.com/  'Optional Title Here'
[foo]: http://example.com/  (Optional Title Here)
[foo]: <http://example.com/longish/path/to/resource/here>
    "Optional Title Here"

Link definitions are only used for creating links during Markdown processing, and are stripped from your document in the HTML output.

Link definition names may consist of letters, numbers, spaces, and punctuation – but they are not case sensitive. E.g. these two links:

[link text][a]
[link text][A]

are equivalent.

The implicit link name shortcut allows you to omit the name of the link, in which case the link text itself is used as the name. Just use an empty set of square brackets – e.g., to link the word “Google” to the google.com web site, you could simply write:

[Google][]

And then define the link:

[Google]: http://google.com/

Because link names may contain spaces, this shortcut even works for multiple words in the link text:

Visit [Daring Fireball][] for more information.

And then define the link:

[Daring Fireball]: http://daringfireball.net/

Link definitions can be placed anywhere in your Markdown document. I tend to put them immediately after each paragraph in which they’re used, but if you want, you can put them all at the end of your document, sort of like footnotes.

Here’s an example of reference links in action:

I get 10 times more traffic from [Google] [1] than from
[Yahoo] [2] or [MSN] [3].

  [1]: http://google.com/        "Google"
  [2]: http://search.yahoo.com/  "Yahoo Search"
  [3]: http://search.msn.com/    "MSN Search"

I get 10 times more traffic from Google than from Yahoo or MSN.

Using the implicit link name shortcut, you could instead write:

I get 10 times more traffic from [Google][] than from
[Yahoo][] or [MSN][].

  [google]: http://google.com/        "Google"
  [yahoo]:  http://search.yahoo.com/  "Yahoo Search"
  [msn]:    http://search.msn.com/    "MSN Search"

Both of the above examples will produce the following HTML output:

<p>I get 10 times more traffic from <a href="http://google.com/"
title="Google">Google</a> than from
<a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a>
or <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</p>

For comparison, here is the same paragraph written using Markdown’s inline link style:

I get 10 times more traffic from [Google](http://google.com/ "Google")
than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
[MSN](http://search.msn.com/ "MSN Search").

I get 10 times more traffic from Google than from Yahoo or MSN.

The point of reference-style links is not that they’re easier to write. The point is that with reference-style links, your document source is vastly more readable. Compare the above examples: using reference-style links, the paragraph itself is only 81 characters long; with inline-style links, it’s 176 characters; and as raw HTML, it’s 234 characters. In the raw HTML, there’s more markup than there is text.

With Markdown’s reference-style links, a source document much more closely resembles the final output, as rendered in a browser. By allowing you to move the markup-related metadata out of the paragraph, you can add links without interrupting the narrative flow of your prose.

Markdown supports a shortcut style for creating “automatic” links for URLs and email addresses: simply surround the URL or email address with angle brackets. What this means is that if you want to show the actual text of a URL or email address, and also have it be a clickable link, you can do this:

<http://example.com/>

Markdown will turn this into:

<a href="http://example.com/">http://example.com/</a>

http://example.com/

Automatic links for email addresses work similarly, except that Markdown will also perform a bit of randomized decimal and hex entity-encoding to help obscure your address from address-harvesting spambots. For example, Markdown will turn this:

<[email protected]>

into something like this:

<a href="&#x6D;&#x61;i&#x6C;&#x74;&#x6F;:&#x61;&#x64;&#x64;&#x72;&#x65;
&#115;&#115;&#64;&#101;&#120;&#x61;&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;
&#109;">&#x61;&#x64;&#x64;&#x72;&#x65;&#115;&#115;&#64;&#101;&#120;&#x61;
&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;&#109;</a>

address@example.com

which will render in a browser as a clickable link to “[email protected]”.

(This sort of entity-encoding trick will indeed fool many, if not most, address-harvesting bots, but it definitely won’t fool all of them. It’s better than nothing, but an address published in this way will probably eventually start receiving spam.)

Anchor Links {: #anchor }

Markdown links to whatever is inside parens (), so you are free to use anchors. Assuming you have some sections defined (see section on attributes below), you can link to them like this:

* [Linking](#linking)
    * [Automatic Links](#autolinks)
    * [Anchor Links](#anchor)

e.g.

Footnotes {: #footnotes }

Calepin supports the MarkdownExtra footnote notation:

That's some text with a footnote.[^1]

[^1]: And that's the footnote.

Results in

<p>That's some text with a footnote.<sup id="fnref:1"><a href="#fn:1" rel="footnote">1</a></sup></p>

and later…

<li id="fn:1">
<p>And that's the footnote.&#160;<a href="#fnref:1" rev="footnote" title="Jump back to footnote 1 in the text">&#8617;</a></p>
</li>

e.g. That’s some text with a footnote.[1] [2]: And that’s the footnote.

Emphasis {: #emphasis }

Markdown uses _ and * to indicate emphasis. Text surrounded by a single underscore or asterisk gets HTML <em> emphasis, and text surrounded by a double underscore or asterisk gets <strong> emphasis. Text with a triple asterisk or underscore is both bold and italics. For example, the following code:

_Single Underscore_
__Double Underscore__
___Triple Underscore___
*Single Asterisk*
**Double Asterisk**
***Triple Asterisk***

Produces:

<p><em>Single Underscore</em>
<strong>Double Underscore</strong>
<strong><em>Triple Underscore</em></strong>
<em>Single Asterisk</em>
<strong>Double Asterisk</strong></p>
<strong><em>Triple Asterisk</em></strong>

Simple tables {: #tables }

This

First Header  | Second Header
------------- | -------------
Content Cell  | Content Cell
Content Cell  | Content Cell

Produces

<table>
<thead>
<tr>
<th>First Header</th>
<th>Second Header</th>
</tr>
</thead>
<tbody>
<tr>
<td>Content Cell</td>
<td>Content Cell</td>
</tr>
<tr>
<td>Content Cell</td>
<td>Content Cell</td>
</tr>
</tbody>
</table>

Which looks like

First Header Second Header
Content Cell Content Cell
Content Cell Content Cell

Markdown formatting can be done within cells:

| Function name | Description                    |
| ------------- | ------------------------------ |
| `help()`      | Display the help window.       |
| `destroy()`   | **Destroy your computer!**     |

Produces

<table>
<thead>
<tr>
<th>Function name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>help()</code></td>
<td>Display the help window.</td>
</tr>
<tr>
<td><code>destroy()</code></td>
<td><strong>Destroy your computer!</strong></td>
</tr>
</tbody>
</table>

Rendered like

Function name Description
help() Display the help window.
destroy() Destroy your computer!

Definition lists {: #definitions }

Definition lists work, but are not styled by Calepin

The code

Apple
:   Pomaceous fruit of plants of the genus Malus in
    the family Rosaceae.

Orange
:   The fruit of an evergreen tree of the genus Citrus.

Results in

<dl>
<dt>Apple</dt>
<dd>Pomaceous fruit of plants of the genus Malus in
the family Rosaceae.</dd>
<dt>Orange</dt>
<dd>The fruit of an evergreen tree of the genus Citrus.</dd>
</dl>
Rendered as
Apple
Pomaceous fruit of plants of the genus Malus in the family Rosaceae.
Orange
The fruit of an evergreen tree of the genus Citrus.

Abbreviations {: #abbreviations }

Calepin supports MarkdownExtra abbreviations. For example:

*[HTML]: Hyper Text Markup Language
*[W3C]:  World Wide Web Consortium

The HTML specification is maintained by the W3C.

Results in:

<p>The <abbr title="Hyper Text Markup Language">HTML</abbr> specification is maintained by the <abbr title="World Wide Web Consortium">W3C</abbr>.</p>

Note that abbreviations are not styled… hover your pointer over HTML or W3C in this paragraph. [HTML]: Hyper Text Markup Language [W3C]: World Wide Web Consortium

Attribute Lists {: #attrs }

{: #someid .someclass somekey=’some values’ }

Use a hash # to set the id of an element, and a dot . to add to an element’s list of classes.

Attributes: Block Level {: #blockattrs }

To define attributes for a block level element, the attribute list should be defined on the last line of the block by itself.

This is a paragraph.
{: #an_id .a_class }

Results in

<p class="a_class" id="an_id">This is a paragraph.</p>

i.e.

This is a paragraph. {: #an_id .a_class }

The exception is headers, which are only allowed on one line.

A setext style header {: #setext}
=================================

### A hash style header ### {: #hash }

Results in

<h1 id="setext">A setext style header</h1>
<h3 id="hash">A hash style header</h3>

And

Header 1            {#header1}
========
## Header 2 ##      {#header2}

Results in

<h1 id="header1">Header 1</h1>
<h2 id="header2">Header 2</h2>

Attributes: Inline Level {: #inlineattrs }

To assign attributes inline, give the attribute list immediately after the inline element with no whitespace.

[link](http://example.com){: class="foo bar" title="Some title!" }

The above results in the following output:

<p><a class="foo bar" href="http://example.com" title="Some title!">link</a></p>

e.g. link{: class=“foo bar” title=“Some title!” }

Using reStructuredText {: #rst }

Calepin supports reStructuredText documents. These need to have a .rst extension. The preamble for reStructuredText files is different than that of Markdown files, but still needs :Title: and :Date: metadata to be processed by Calepin.

A reStructuredText Document
===========================

:Title: A ReStructuredText Test
:Date: 2012-04-19

  1. 1  ↩

  2. 1  ↩