Format to use for converted wiki pages

[will-henney]

The GitHub wiki is powered by Gollum (with some features disabled). Each file has an underlying markup format (e.g., markdown, textile) but there is also a basic wiki syntax (MediaWiki-inspired) overlaid on that. The simplest example is [[OtherPage]] becomes an internal link to a a file OtherPage.md (assuming markdown) in the same wiki. For more examples, see the link above.

My recommendation is that we standardize on markdown for the wiki for the following reasons:

1. It is the default choice that is offered when you create a new page.
2. It is what is supported everywhere else on GitHub, e.g., issues
3. It is the last format that will ever be axed. At the moment GitHub is in a crazy expansion phase with all the cash and hirings that will have followed the Microsoft acquisition. But this won't last forever, and in the future there may be contraction.
4. Widespread tooling support. For instance, WorkingCopy iOS app for edits on the go!

There remains the question as to whether to use the wiki link syntax, or the native markdown link syntax, or both. In the automatic conversion (see test-trac2down.py), I have gone for a mixed strategy. I am using a python script trac2down.py from the tracboat project, which converts to vanilla markdown, taking care of the conversion of section headers, bold/italic, inline and block code, external links, etc. Then I have my own function, which makes a list of all the wiki pages and then converts any apparent internal links to the Gollum format (in Trac, you just write OtherPage but on GitHub it has to be [[OtherPage]]). I try to skip over anything in a code block or verbatim section, but there were still a few false positives. These can easily be fixed by hand.

So that has been my basic strategy and justification, but I am open to other ideas if anyone feels strongly. So any comments or questions are welcome.

[will-henney]

Test of mentions: calling @cloudy-astrophysics/nublado-migration-team !