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
>
>

Reply via email to