Table of Contents

Default Markdown Extensions
Enabling a Table of Contents

These are some tips and tricks for your Markdown pages (.md files).

Rophako treats Markdown pages as first-class citizens. For example, just like how the /about URI on your site can map to an HTML file named about.html, you could also have used a Markdown file named about.md if you prefer to write some of your pages in Markdown (you can mix and match HTML and Markdown pages within a site, but don't use both for the same page!)

Rophako includes a minimalistic template at rophako/www/markdown.inc.html that simply drops the rendered HTML from the Markdown and sets the page title to match the first header in the Markdown source. You can override the default Markdown template by creating a markdown.inc.html in your site's own document root.

Default Markdown Extensions

The following Markdown extensions are on by default in Rophako; this applies to all places where Markdown is supported, including blog posts and comments:

fenced_code: GitHub style code blocks.
tables: Markdown tables, from php-markdown (information)
smart_strong: Handles double__underscore better.
codehilite: Highlights source code using Pygments -- useful with GitHub style code blocks.
nl2br: Line breaks inside a paragraph become a literal <br> in the HTML.
sane_lists: Make lists less surprising.

You can enable or disable extensions on a per-page basis by using "meta" tags in your Markdown files.

At the very top of your Markdown file, a line beginning with the string :meta is a "meta" tag. Example:

:meta extensions -nl2br headerid

This example disables (note the minus sign) the nl2br extension, and enables headerid (adding HTML anchor IDs to each header).

See the Extensions documentation in the Python Markdown module.

Enabling a Table of Contents

To enable a Table of Contents on one of your Markdown pages, you need to do two things:

Enable the headerid extension
Turn on the table of contents setting

The headerid extension generates anchor tags for all the headers on your page, like:

<h1 id="getting-started">Getting Started</h1>

And the TOC setting tells Rophako to parse the generated HTML to find those anchor tags and create a Table of Contents.

For a minimal example, put this at the top of your Markdown file:

:meta extensions headerid
:meta toc on

Rophako's default Markdown template will generate markup like the following:

<nav class="markdown-toc">
  <ul>
    <li class="toc-1">
      <a href="#introduction">Introduction</a>
    </li>
    <li class="toc-2">
      <a href="#before-we-begin">Before We Begin</a>
    </li>
    <li class="toc-1">
      <a href="#synopsis">Synopsis</a>
    </li>
  </ul>
</nav>

The key classes:

.markdown-toc: the wrapper for the entire Table of Contents nav object, so you can style this however you want, e.g. place it in a fixed side bar.
.toc-1 through .toc-6: these correspond to the header level of the item (<h1> through <h6>) so you can style them appropriately (e.g. indent the subheaders)

The default Rophako web design doesn't contain any special classes for Table of Contents, so you should implement these for your own site's theme.