Markdown WikiProcessor Macro Implementation

Description

This macro implements John Gruber's ​Markdown lightweight plain text-to-HTML formatting syntax as a wiki processor macro.

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 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.

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

Enable the macro in your trac.ini file:

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

If you want to use markdown without wrapping the text in a WikiProcessor:

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

The markdownformatter and markdownmacro components are mutually exclusive and should not be both enabled.

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

Note: this is a Trac addition

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 addition

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()]]

}}}

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