On Mon, May 23, 2016 at 6:09 PM, Matt Micene <nzwul...@gmail.com> wrote:
> 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 > > > I have registry docs rendering html[1] using asciibinder[2]. I would recommend the addition of asciibinder only if you need multiple content set and/or branded distributions of the docs. I think the projectatomic template work I did[3] would be useful to this effort regardless. [1] http://docs.projectatomic.io/registry/ [2] http://www.asciibinder.org/ [3] look for "atomic" files: https://github.com/openshift/openshift-docs/tree/master/_templates > 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. > > Cheers, > - Matt M > >
