Markdown Basics December 10, 2015

Markdown

Markdown is a popular text format for editing files. It is often used to produce well formatted web content. It is used extensively by GitHub, Reddit, Stack Overflow, and many others.

One of the easiest ways to become familiar with Markdown is to give it a try!

Text formatting

Bold, italics, lists

*This is italic*

**This is bold**

This sentence has **bold**, *italics*, and ***bold-italics***

* This is a list item
* So is this
    * And this is a sublist item

Numbered lists are easy

1. First item
2. Second item
    1. Sub second item
3. Third item

The above Markdown produces the following HTML

<p><em>This is italic</em></p>

<p><strong>This is bold</strong></p>

<p>This sentence has <strong>bold</strong>, <em>italics</em>, and <strong><em>bold-italics</em></strong></p>

<ul>
    <li>This is a list item</li>
    <li>So is this
        <ul><li>And this is a sublist item</li></ul>
    </li>
</ul>

<p>Numbered lists are easy</p>

<ol>
    <li>First item</li>
    <li>Second item
        <ol><li>Sub second item</li></ol>
    </li>
    <li>Third item</li>
</ol>

Headings

If you enter the following in your Markdown (.md) files:

<h1>An HTML h1 heading</h1>

# An h1 heading

Also an h1 heading
==================

## An h2 heading

Also an h2 heading
------------------

### An h3 heading

#### An h4 heading

You would see the following HTML on your page:

<h1>An HTML h1 heading</h1>

<h1>An h1 heading</h1>

<h1>Also an h1 heading</h1>

<h2>An h2 heading</h2>

<h2>Also an h2 heading</h2>

<h3>An h3 heading</h3>

<h4>An h4 heading</h4>
...
Extensions December 10, 2015

PyKwiki Extensions

MarkDown Extensions

pykwiki.ext.post

Warning: This documentation is only compatible with version 1.0 and newer.

This extension is not compatible with the wikilink markdown extension.

This extension syntax is:

[[page<:optional property>]]

Assuming you have a post in source called home.md with title set to "Home", then the following MarkDown:

Here is a link to [[home]]

Generates the following HTML:

<p>Here is a link to <a href="/home.html" class="postlink">Home</a></p>

Similar things can be achieved with title, blurb, url, and description:

This is a link to [[home]], known as [[home:title]], found at [[home:url]]
[[home:blurb]]
[[home:description]]

Will create:

<p>This is a link to <a href="/home.html" class="postlink">Home</a>, known as Home, found at /home.html
   This is just an example post used for testing random junk.
   This is just an example post used for ...</p>

Post sections

New in version 1.0.3

One of the more poweful features of the post markdown extension is the ability to include sections from other pages.

You can specify a page section with {section:name} and {endsection}.

For example, in a page called faqs.md, you could add a section such as the following:

::: text
{section:foo}
# This is a section about foo

To learn more about foo, see <a href="foo">Foo</a>.
{endsection}

Then to include that section in another page:

Below is a section from the FAQs page:
[[faqs:section:foo]]

pykwiki.ext.tpl

This extension allows for templates to be included in your source files. See Helper Templates for examples.

The basic usage is:

{tpl:template_name}
key: value
{endtpl}

The above code will attempt to render a Jinja2 template named template_name.tpl inside of your source directory.

Example

If you have a template called project.tpl located in base_path/source, and it contains the following content:

# {{name}}
* Description: {{description}}
* url: [{{url}}]({{url}})

And you include the following in one of your md pages.

{tpl:project}
name: Widget System
description: A fun widget system for everyone!
url: http://widgets.com
{endtpl}

Then PyKwiki will render project.tpl with the data from {tpl:project} into the HTML, like so:

<h1>Widget System</h1>
<ul>
    <li>Description: A fun widget system for everyone!</li>
    <li>url: <a href="http://widgets.com">http://widgets.com</a></li>
</ul>

pykwiki.ext.uml

New in version 1.0.8

This extension is powered by Plant UML and requires python-plantuml to be installed.

Installation

sudo pip install plantuml

Then add pykwiki.ext.uml to your config.yaml extensions section.

Example

{uml}
Alice -> Bob: Connection
Bob -> Marge: Another connection
note left: This is just a note
{enduml}

The above produces the following HTML by default.

<img src="http://www.plantuml.com/plantuml/img/utBCoKnELT2rKt3AJx9ISCxFoqjDBidCp-C2ya72leb5wQbM2evv-IKPgKKAoGW50000"/>

Live example

...