[[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. 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 [https://python-markdown.github.io/extensions/md_in_html/ Markdown in HTML].
* Footnotes.
* Tables.
* Markdown as [#MarkdownasWikiLanguage default wiki language].

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 plugin depends on [pypi:Markdown 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 [pypi:Markdown Python Markdown] package which is automatically installed.

{{{#!box note
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#InstallingaTracplugin 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.
{{{#!ini
[components]
tracmarkdown.macro.markdownformatter = enabled
tracmarkdown.macro.markdownmacro = enabled
}}}

== Configuration

The following may be set in `trac.ini`.

{{{#!ini
[markdown]
root_pages = Docs, Note
tab_length = 4
}}}

{{{#!tr
{{{#!td
`root_pages`
}}}
{{{#!td
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.[[BR]][[BR]]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:
{{{#!ini
[markdown]
root_pages = Docs, Note
}}}
**Note:** page names are case sensitive.
}}}
{{{#!td
(no default)
}}}
}}}
{{{#!tr
{{{#!td
`tab_length`	
}}}
{{{#!td
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.
}}}
{{{#!td
4
}}}
}}}

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

You may use WikiProcessors in your Markdown text by either
* use [#Codefencesyntax 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: 
{{{#!ini
[markdown]
root_pages = Docs, Note
}}}

**Note:** page names are case sensitive. 

{{{#!box width=720
==== Markdown as wiki language
[[Image(markdown_wikipage.png, width=700)]]
}}}
== 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]