[[PageOutline(2-3,Contents)]]

= Markdown

[http://daringfireball.net/projects/markdown/basics/ Markdown] is a semi-structured markup language originally designed for blogs, which is now used in several wikis as well.

It is now widely used in the software developer community, because it is the preferred authoring markup used by GitHub and StackOverflow.
See [http://github.github.com/github-flavored-markdown/ Introduction to GFM] and  [http://stackoverflow.com/editing-help/ Markdown help] respectively for what variant is supported in each.

The syntax shares many similarities with WikiCreole, ReST and our own markup. Therefore, the markdown syntax would fit well with our current syntax, in particular the rules for nesting paragraphs. The new WikiEngine should also make it possible to implement optional or conditional support for Markdown, for the features that conflict with the current syntax.

This page lists the details of the basic syntax, the advanced syntax and its popular extensions.

== [http://daringfireball.net/projects/markdown/basics Basic features]

=== PARAGRAPHS, HEADERS, BLOCKQUOTES

{{{
A First Level Header
====================

A Second Level Header
---------------------

Now is the time for all good men to come to
the aid of their country. This is just a
regular paragraph.

The quick brown fox jumped over the lazy
dog's back.

### Header 3

> This is a blockquote.
> 
> This is the second paragraph in the blockquote.
>
> ## This is an H2 in a blockquote
}}}

The first level and second level headers are really a thing to have, as it's also supported in reStructuredText.

The `###` for sections is problematic, as this conflicts with WikiCreole's numbered lists.

=== PHRASE EMPHASIS

{{{
Some of these words *are emphasized*.
Some of these words _are emphasized also_.

Use two asterisks for **strong emphasis**.
Or, if you prefer, __use two underscores instead__.
}}}

These ones must be handled with care.

=== LISTS

Unnumbered lists, same as us with `*` and `-` but also `+`.
Numbered lists, same as us.

**But**:
{{{
*   A list item.

    With multiple paragraphs.

*   Another item in the list.
}}}

This is a huge win and one of the main motivations behind the new engine. (see #8140, #1936)

=== LINKS

This:
{{{
This is an [example link](http://example.com/).
}}}

and that:
{{{
This is an [example link](http://example.com/ "With a Title").
}}}

References:

{{{
I get 10 times more traffic from [Google][1] than from
[Yahoo][2] or [MSN][3].

[1]: http://google.com/        "Google"
[2]: http://search.yahoo.com/  "Yahoo Search"
[3]: http://search.msn.com/    "MSN Search"

I start my morning with a cup of coffee and
[The New York Times][NY Times].

[ny times]: http://www.nytimes.com/
}}}

=== IMAGES

{{{
![alt text](/path/to/img.jpg "Title")

![alt text][id]

[id]: /path/to/img.jpg "Title"
}}}

So we'll have to find another way than the usual `!...` for escaping links. In Markdown, it's usually `\` which is used for escaping markup.

At first it looks like a very simple alternative to the Image macro, however I've seen things like:
{{{
[![Build Status](https://secure.travis-ci.org/libgit2/libgit2.png?branch=development)](http://travis-ci.org/libgit2/libgit2)
}}}

i.e. the image link can be written inside the label part of a normal link (like other inline markup), which can be a challenge! But we also wanted that already for our own TracLinks, see #9123.

Note that tricky stuff like {{{[`o]o`](http://example.com)}}} easily confuses the GitHub parser.

=== CODE

We have {{{`...`}}} also.

But see below.

== [http://daringfireball.net/projects/markdown/syntax Advanced features]

=== INLINE HTML

{{{
This is a regular paragraph.

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

This is another regular paragraph.
}}}

The original spec mention that the content of these elements is not parsed as Markdown, but some [http://michelf.ca/projects/php-markdown/extra/#markdown-attr extensions] allow for it.

So this *might* be an alternative to our WikiProcessors for WikiHtml.

=== BLOCKQUOTES

"Markdown allows you to be lazy and only put the > before the first line of a hard-wrapped paragraph:"
{{{
> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
id sem consectetuer libero luctus adipiscing.
}}}

=== LISTS

"It looks nice if you indent every line of the subsequent paragraphs, but here again, Markdown will allow you to be lazy:"
{{{
*   This is a list item with two paragraphs.

    This is the second paragraph in the list item. You're
only required to indent the first line. Lorem ipsum dolor
sit amet, consectetuer adipiscing elit.

*   Another item in the same list.
}}}

This breaks the base assumption of the [TracDev/Proposals/VerticalHorizontalParsing vertical/horizontal parsing].

=== CODE

{{{
``There is a literal backtick (`) here.``
}}}

== [https://help.github.com/articles/github-flavored-markdown GitHub Flavored Markdown]

=== Newlines

This is our "standard" //respect new line// setting. Applied in tickets, not in wiki pages.

=== Multiple underscores in words

Sure, perform_complicated_task shouldn't become perform//complicated//task. 

We could even auto-verbatim these.

=== URL autolinking

We have this feature already.

=== Fenced code blocks

{{{
```
verbatim
         text 
              here

```
}}}
With optional syntax-highlighting: {{{```ruby}}}.

Well, in fact our usual `#!processor args` should apply here ({{{```processor args}}}).

See #10734.

=== [https://github.com/blog/1375-task-lists-in-gfm-issues-pulls-comments Task Lists]

Aha! Thought about them since a long time, and finally GitHub did it.

It's only possible to support it if we're able to rewrite the original wiki text from the parsed data.

=== Quick quoting

Well, that's more an UI thing, but why not.

=== Name and Team @mentions autocomplete

Once we have a better notion of users. But `@user` syntax seems to have become the de-facto standard (I would have preferred ~user though).

Auto-complete could be used for a great deal of other things (WikiPageNames and WikiMacros, source paths, attachment names, etc. See #9296).

=== Emoji autocomplete

Some kind of integration with the WikiExtras `(|...|)` -> `:...:`.

=== Issue autocompletion

Intelligent auto-completion, perhaps even with filtering. Well, this is also an UI topic, nothing special about the syntax.

=== Zen Mode (fullscreen) writing

Also UI.

=== Closing issues via commit messages

We have this feature already.

=== References

{{{
* SHA: be6a8cc1c1ecfe9489fb51e4869af15a13fc2cd2
* User@SHA ref: mojombo@be6a8cc1c1ecfe9489fb51e4869af15a13fc2cd2
* User/Project@SHA: mojombo/god@be6a8cc1c1ecfe9489fb51e4869af15a13fc2cd2
* \#Num: #1
* User/#Num: mojombo#1
* User/Project#Num: mojombo/god#1
}}}

References to SHA1 numbers are/should be unique enough for not having to ask the user to add the repository name. However, if it's added, then we know explicitly where to go (in case the same commit is present in multiple repositories).

== [http://michelf.ca/projects/php-markdown/extra/ Markdown Extra]

== [http://fletcherpenney.net/multimarkdown/ MultiMarkdown]

 * footnotes
 * tables
 * citations and bibliography (works best in LaTeX using BibTeX)
 * math support
 * automatic cross-referencing ability 
 * smart typography, with support for multiple languages
 * image attributes
 * table and image captions
 * definition lists
 * glossary entries (LaTeX only)
 * document metadata, such as title, author, etc.

== [http://johnmacfarlane.net/pandoc/README.html#pandocs-markdown Pandoc]

== [http://www.pell.portland.or.us/~orc/Code/markdown/ Discount]

== [http://stackoverflow.com/editing-help StackOverflow extensions]

== [http://rdoc.rubyforge.org/RDoc/Markdown.html RDoc Markdown]

== [http://www.stack.nl/~dimitri/doxygen/manual/markdown.html Doxygen Markdown]