Create folder structure for documents relating to approved proposals

[mikecroft]

Each approved proposal should have its own subdirectory under proposals.

Within here, we can use asciidoc's include statements to simply reference documentation which resides in the evolution-proposals repository, for example:

include::https://raw.githubusercontent.com/eclipse/microprofile-evolution-process/master/proposals/0003-health-checks.md[]

The above syntax, in asciidoc, will include the content of the health checks proposal. This means that we can centralise documentation without moving its physical location or duplicating content.

This would mean converting existing proposal documents from MarkDown to AsciiDoc, however. At this stage, I don't think that's too challenging with the number of current proposals - I'd be happy to do that myself. Currently, the .md files don't render exactly correctly, but they are still very legible.

[mikecroft]

It turns out that GitHub's asciidoc renderer doesn't support this feature. In my local AsciidocFX, everything works beautifully. https://github.com/mikecroft/microprofile/blob/POC-folder-structure-%2311/proposals/MP-0003-health-checks/proposal.adoc

The single-line rendering properly in AsciidocFX:

I tried this in GitBooks as well, but I've found the same behaviour, so I don't know if they maybe share a renderer. I also found the behaviour didn't change if I was linking an adoc rather than md file.

[mikecroft]

There is a solution to this - we could convert this repository to a GitHub Pages website, since there is an AsciiDoctor plugin for Jekyll which supports the include directive: https://github.com/asciidoctor/jekyll-asciidoc

I will try a POC for this when I can.

[kwsutter]

Mike, what about just providing a link to the various proposals? Couldn't read it inline, but it would still be pretty easy to get to the articles in the other repos... Something like this:

link: https://raw.githubusercontent.com/eclipse/microprofile-evolution-process/master/proposals/0003-health-checks.md[MicroProfile Health Check proposal]

On Fri, Feb 24, 2017 at 4:53 AM, Mike Croft notifications@github.com wrote:

There is a solution to this - we could convert this repository to a GitHub Pages website, since there is an AsciiDoctor plugin for Jekyll which supports the include directive: https://github.com/asciidoctor/jekyll-asciidoc

I will try a POC for this when I can.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/eclipse/microprofile/issues/11#issuecomment-282263293, or mute the thread https://github.com/notifications/unsubscribe-auth/AHXkL8KsWeD9siGJSHKy_BavcHZZXanhks5rfrajgaJpZM4MLDFS .

[OndroMih]

No longer relevant