[[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:

{{{
{{{#!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

First you need to install the [pypi:Markdown Python Markdown] package.
Follow the instructions on the Web site.

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.

== 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]