[che-dev] PR: Convert Che docs to Asciidoc

[Robert Kratky <rkratky@xxxxxxxxxx>]

Hi all,

I have just submitted a PR to the Che docs repo [1] that converts the entire Che docs set from Markdown to Asciidoc(tor). I have provided a detailed explanation and reasoning for the move in the corresponding issue [2].

To quote from the issue: "AsciiDoc, while rather similar to Markdown in the simplicity of its syntax, offers, among other things:

* better formatting capabilities
* semantic tagging (useful for CI testing)
* native xrefs (links to other parts of the docs)
* macros and variables
* combining docs through native inclusions"

The PR outlines the proposed changes.

The change from one mark-up language to another should be totally transparent and barely noticeable for users. The converted site still uses Jekyll to generate the HTML, and the look & feel has not changed. All navigation and other site elements are unchanged.

Please, review and comment. Due to the scope of the PR, it would be great if it could be merged quickly (provided there are no objections), so that regular work on the docs can resume without necessitating a rerun of the conversion scripts.

Thanks for considering.

[1] https://github.com/eclipse/che-docs/pull/456
[2] https://github.com/eclipse/che-docs/issues/425

Regards,

--
Robert Krátký
P. Technical Writer, CCS
Red Hat Czech