On 05/23/2016 02:44 PM, Josh Berkus wrote:
On 05/23/2016 06:03 AM, Preeti Chandrashekar wrote:
Hi All,
In line with our ongoing efforts at streamlining the docs process, and
in order to ensure better upstream-downstream coordination, we
are proposing to move to the Asciidoc format for docs related to
container development tools in Project Atomic.
I'm happy for this to be our default, but I'm concerned about making
existing projects port their docs. For one thing, at least a couple of
projects make use of readthedocs.org, which requires a different format.
I ran the current set of docs through pandoc and spit out asciidoc
versions a few weeks ago. I didn't want to make this an official PR at
this point but a place to look at the results.
https://github.com/nzwulfin/atomic-site/tree/adoc
Things that you need to know:
* authoring an AsciiDoc document that Middleman (and Jekyll for that
matter) still wants a YAML front matter block to recognize it as a doc /
post. The blocks here are blank, but could include title: like before.
It doesn't seem to matter to basic operations.
* the current rendering for AsciiDoc isn't particularly pretty. The
Table at the top of the Getting Started Guide, for example, looks like
tab delimited text. Section headings also get pretty small quickly. So
we'd need to explore rendering.
Otherwise, that branch is a functional starting point. Folks more
familiar with how we're using Middleman can probably chime in on the use
of vars defined in the front matter block and if those need to be added
back in.