On 05/23/2016 02:44 PM, Josh Berkus wrote:
On 05/23/2016 06:03 AM, Preeti Chandrashekar wrote: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.
Hi All,I'm happy for this to be our default, but I'm concerned about making
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.
existing projects port their docs. For one thing, at least a couple of
projects make use of readthedocs.org, which requires a different format.
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.
- Matt M