Markdown WikiProcessor Macro Implementation

Description

This macro implements John Gruber's ​Markdown lightweight plain text-to-HTML formatting syntax as a wiki processor macro. It comes with Markdown extensions to better integrate with the Trac wiki.

• Supports WikiProcessors in Markdown text.
• It's possible to use WikiMacros.
• Supports TracLinks.
• Syntax highlighting for source code if enabled in Trac.
• Full support for inline HTML and ​Markdown in HTML.
• Footnotes.
• Tables.
• Markdown as default wiki language.

Example of its usage:

{{{#!Markdown

# RGB

+ Red
+ Green
+ Blue

## Source Code

    from trac.core import *
    from trac.wiki.macros import WikiMacroBase
    from trac.wiki.formatter import Formatter

An example [link](http://example.com/ "With a Title").

A table:

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

Alternatively, enabling the MarkdownFormatter component will render wiki content as Markdown throughout Trac, without needing to wrap the text in a WikiProcessor. See installation for details.

See also:

• John Gruber's ​Markdown.
• ​Python Markdown.
• ​Markdown syntax.

Bugs/Feature Requests

Existing bugs and feature requests for MarkdownMacro are here.

If you have any issues, create a new ticket.

defect	10 / 14
enhancement	6 / 6
task	1 / 1

Download

Download the zipped source from here.

The plugin is also available on ​PyPI.

Source

You can check out MarkdownMacro from here using Subversion, or browse the source​ with Trac.

Installation

The plugin depends on ​Python Markdown.

The easiest way to install this macro is from source using PIP:

pip install https://trac-hacks.org/svn/markdownmacro/trunk

This takes care of the ​Python Markdown package which is automatically installed.

Note that for Trac 1.4 Markdown < 3.2 must be used because the library dropped Python 2 support with v3.2. This is ensured when using PIP.

General instructions on installing Trac plugins can be found on the TracPlugins page.

Enable the macro and the wiki page formatter in your trac.ini file. This can also be done using the plugin admin page.

[components]
tracmarkdown.macro.markdownformatter = enabled
tracmarkdown.macro.markdownmacro = enabled

Configuration

The following may be set in trac.ini.

[markdown]
root_pages = Docs, Note
tab_length = 4

root_pages	List of wiki page names to be used as root pages for a page hierarchy. Wiki subpages of these roots will use Markdown as the default wiki language. For example if the list contains Docs, Note the wiki pages Docs/MyDocument and Note/FirstNote will use Markdown; the wiki page NoteOne will use Trac WikiFormatting. Example: [markdown] root_pages = Docs, Note Note: page names are case sensitive.	(no default)
tab_length	Specify the length of tabs in the markdown source. This affects the display of multiple paragraphs in list items, including sub-lists, blockquotes, code blocks, etc.	4

Usage

The general ​Markdown syntax is supported by the macro. In addition the ​Markdown extra extension is enabled which brings support for ​tables, ​footnotes and more.

Some of Tracs syntax was added to Markdown so WikiProcessors, WikiMacros and ticket links can be used seamlessly.

Basic usage

The macro can only be used as a WikiProcessor.

{{{#!Markdown
# A Header

This is *all* Markdown.
}}}

Links

Since the full ​Markdown syntax is implemented links can be specified in different ways. Using a link section in your Markdown text holding all references may be especially useful for structuring the content.

{{{#!Markdown
# Using links

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

Link defined with [an id][id] somewhere in the text.

Implicit links work: [Bar link][]

Autolink: <http://example.com/foo>

## Links below but not rendered

[id]: <http://example.com/foo>  "Foo Title Here"

[foo]: http://example.com/foo  "Foo Title Here"

[Bar link]: http://example.com/bar  "Bar Title Here"

}}}

For more visit the ​Markdown syntax page.

Inline HTML

HTML tags can be used whenever needed.

{{{#!Markdown
# A Header

This is *all* Markdown but HTML tags can be used when needed:

<table>
    <tr>
        <td>Foo</td>
    </tr>
</table>

}}}

Because the ​Markdown in HTML extensions is enabled it is possible to wrap Markdown text in tags and still have the Markdown parsed.

Note the attribute markdown in the following example. See ​Markdown in HTML for possible values.

{{{#!Markdown
# A Header

<div style="border: 1px solid grey;" markdown="1">
  This is Markdown _text_ with *formatting*.    
</div>

}}}

This can also be used with Trac features like WikiMacros:

{{{#!Markdown
# A Header

<div style="border: 1px solid grey;" markdown="1">
  [[TracIni()]]    
</div>

}}}

TracLinks

Note: this is a Trac addition

TracLinks are supported with the following syntax:

[Trac link specifier]

for example:

[ticket:2]

[changeset:18323 Changest 18323]

Shortcut notations like r18323 or ticket:12000 are not working so always add the brackets.

Wiki links

The Markdown ​WikiLinks syntax is supported:

A link to [[WikiStart]].

In addition you may use TracLinks notation if you want to use another label.

Use TracLinks notation with [WikiStart Startpage].

Note: the second variant is a Trac addition

Using WikiProcessors

You may use WikiProcessors in your Markdown text by either

• use Code fence syntax
• or use Trac WikiProcessors syntax

When using Code fence syntax your text will better work with other Markdown editors because any WikiProcessor content will be shown as preformatted text.

Code fence syntax

Use the Markdown code fence syntax like this:

```python
def function():
    foo = 1
```

or with parameters:

```div style="border: 1px solid blue;"
Some text in a blue box.
```

Note that this may break presentation in other editors.

Like with Tracs WikiProcessors the first line of the content may be used for parameters:

```
#!div style="border: 1px solid blue;"
Some text in a blue box.
```

Trac WikiProcessor syntax

Note: this is a Trac only extension.

WikiProcessors can be used without any special escape syntax. Just add the processor to the Markdown text.

{{{#!Markdown
# A Header

This is *all* Markdown but Trac WikiProcessors can be used:

{{{#!python
def function():
    foo = 1
}}}

{{{#!ini
[section]
foo = bar
}}}

}}}

Using WikiMacros

Note: this is a Trac extension

Tracs WikiMacros can be used like with normal Trac wiki syntax.

{{{#!Markdown
# A Header

This is *all* Markdown but Trac WikiMacros can be used:

[[TracIni()]]

}}}

Markdown as Wiki Language

You may specify a list of wiki page names to be used as root pages for a page hierarchy. Wiki subpages of these roots will use Markdown as the default wiki language.

For example if the list contains Docs, Note the wiki pages Docs/MyDocument and Note/FirstNote will use Markdown; the wiki page NoteOne will use Trac WikiFormatting.

Example:

[markdown]
root_pages = Docs, Note

Note: page names are case sensitive.

Markdown as wiki language

Recent Changes

18423 by Cinc-th on 2021-06-03 08:23:45

MarkdownMacro: use Markdown < 3.2 install requirement only for Python 2. For Python 3 (Trac >1.4.x) any release will do.

18422 by Cinc-th on 2021-06-02 06:02:38

MarkdownMacro: removed debug print statement.

18417 by Cinc-th on 2021-06-01 10:33:33

MarkdownMacro: new preview renderer for *.md files. To render README.md und Install.md properly change the following in trac.ini.

[mimeviewer]
mime_map_patterns = text/plain:README(?!(\.md|\.rst))|INSTALL(\.md|\.rst)|COPYING.*

Closes #11743

(more)

Author/Contributors

Author: dwclifton (Macro/Processor package, setup, documentation)
Maintainer: Cinc-th
Contributors:

• ​John Gruber
• ​Yuri Takhteyev, et al.
• Alex Mizrahi alias killer_storm