Created Markdown Pages (markdown)

Markdown-Pages.md

@@ -0,0 +1,75 @@
+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](http://michelf.ca/projects/php-markdown/extra/#table))
+* `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](https://pythonhosted.org/Markdown/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:
+
+```html
+<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:
+
+```html
+<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.