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!
*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>
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>
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>
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]]
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>
New in version 1.0.8
This extension is powered by Plant UML and requires python-plantuml to be installed.
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