Changes between Version 1 and Version 2 of MarkDown

Timestamp:

Mar 6, 2013, 1:24:31 AM (11 years ago)

Author:

Christian Boos

Comment:

some work notes on possible Markdown extensions to the WikiFormatting syntax

MarkDown

@@ -1 +1 @@
 = Markdown
+
+[[PageOutline(2-3)]]
 
 [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.
@@ -6 +8 @@
 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.
 
-
-A lot of this is close to WikiCreole, ReST and our own markup. See also TracDev/Proposals/AdvancedWikiFormatting for some things that could be stolen from it.
+A lot of this is close to WikiCreole, ReST and our own markup. Most of the time, the markdown syntax makes a lot of sense and would fit well with our current syntax (in particular the rules for nesting paragraphs). And the rest is damn interesting as well!
+
+The new WikiEngine should make it possible to implement optional or conditional support for Markdown, for the features that conflict with the current syntax.
+
+So let's go through the details of the basic syntax, of the advanced syntax and of 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 motivator 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/
+}}}
+... challenging.
+
+=== 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).
+
+... challenging again! But we also wanted that already for our own TracLinks, see #9123.
+
+Note that some 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.
+}}}
+
+Damn, 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.
+
+=== 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 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.
+
+=== 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 (e.g. title, author, etc.)
+
+
+-----
+(to be continued)
+-----
+== [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]