[[PageOutline(2-5,Contents,pullout)]]

= Markdown !WikiProcessor Macro Implementation

== Description

This macro implements John Gruber's [http://daringfireball.net/projects/markdown/ Markdown] lightweight plain text-to-HTML formatting syntax as a [WikiProcessors wiki processor] macro.

Example of its [#usage 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 [WikiProcessors WikiProcessor]. See [#Installation installation] for details.

See also:
 * John Gruber's [http://daringfireball.net/projects/markdown/ Markdown].
 * [https://pypi.org/project/Markdown/ Python Markdown].
 * [http://daringfireball.net/projects/markdown/syntax Markdown syntax].

== Bugs/Feature Requests

Existing bugs and feature requests for MarkdownMacro are 
[query:status!=closed&component=MarkdownMacro&order=priority here].

If you have any issues, create a 
[/newticket?component=MarkdownMacro new ticket].

[[TicketQuery(component=MarkdownMacro,group=type,format=progress)]]

== Download

Download the zipped source from [export:markdownmacro here].

The plugin is also available on [pypi:TracMarkdownMacro PyPI].

== Source

You can check out MarkdownMacro from [/svn/markdownmacro here] using Subversion, or [source:markdownmacro 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 [pypi:Markdown Python Markdown] package which is automatically installed.

General instructions on installing Trac plugins can be found on the [TracPlugins#InstallingaTracplugin TracPlugins] page.

Enable the macro in your `trac.ini` file:
{{{#!ini
[components]
tracmarkdown.macro.markdownformatter = disabled
tracmarkdown.macro.markdownmacro = enabled
}}}

If you want to use markdown without
wrapping the text in a [WikiProcessors WikiProcessor]:
{{{#!ini
[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 [http://daringfireball.net/projects/markdown/syntax Markdown syntax] is supported by the macro. In addition the [https://python-markdown.github.io/extensions/extra/ Markdown extra] extension is enabled which brings support for [https://python-markdown.github.io/extensions/tables/ tables], [https://python-markdown.github.io/extensions/footnotes/ 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 [WikiProcessors WikiProcessor].
{{{
{{{#!Markdown
# A Header

This is *all* Markdown.
}}}
}}}

=== Links

Since the full [http://daringfireball.net/projects/markdown/syntax 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 [http://daringfireball.net/projects/markdown/syntax 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 [https://python-markdown.github.io/extensions/md_in_html/ 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 [https://python-markdown.github.io/extensions/md_in_html/ 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 [https://python-markdown.github.io/extensions/wikilinks/ 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

[[ChangeLog(markdownmacro, 3)]]

== Author/Contributors

'''Author:''' [wiki:dwclifton] (Macro/Processor package, setup, documentation) [[BR]]
'''Maintainer:''' [[Maintainer]] [[BR]]
'''Contributors:'''
 * [http://daringfireball.net/colophon/ John Gruber]
 * [http://www.freewisdom.org/projects/python-markdown/Credits Yuri Takhteyev, et al.]
 * Alex Mizrahi alias [/attachment/ticket/353/Markdown.py killer_storm]