[TYPO3-doc] Experimental Markdown support

[Xavier Perseguers]

Hi all,

You may or may not have seen a tweet a while ago about me adding an experimental README.md [*] support for extension authors.

As you know, the documentation team already supports a special form of documentation as a single README.rst [*] (reStructuredText format) at root, in addition to the now official and modern Sphinx project. More information in [1].

Many extension authors are using GitHub to host their extensions and GitHub is highly advertising that one should create a README file at root. However, although GitHub is capable of correctly rendering both reStructuredText README (.rst) and Markdown README (.md), it defaults to Markdown format unless you actively choose the other one. As such, many extensions are now providing a simple README.md file instead of a README.rst single page manual.

As such, I added a conversion step from README.md to README.rst using pandoc when trying to render the extension's manual on docs.typo3.org.

Disclaimer: the version of pandoc we currently have is quite old and does not properly render blocks of code (with triple back ticks). I expect it to be fixed once the server team lets us upgrade the underlying virtual machine OS.

Finally, here a quick summary of rules of what is rendered when you have multiple kind of manuals for your extension:

1) doc/manual.sxw => doc/manual.sxw converted as Sphinx project and featuring a legacy banner on top of each chapter
2) README.md => converted as README.rst
3) README.rst => clear...
4) Documentation/Index.rst => clear...
5) Documentation/Index.rst + doc/manual.sxw or + README.md/rst => Documentation/Index.rst

BEWARE:

6) doc/manual.sxw + README.md/rst => README.rst and the complete manual in doc/manual.sxw WILL NOT be rendered at all

Cheers,
Xavier

[*] Server expects the file to be capitalized exactly like that
[1] http://docs.typo3.org/typo3cms/CoreApiReference/ExtensionArchitecture/Documentation/Index.html