Great topic. I actually hadn't noticed till you pointed it out! > On Dec 9, 2018, at 8:48 AM, Jose Henrique Ventura > <jose.vent...@protonmail.com.INVALID> wrote: > > Hi Folks, > > I see some README.md files have been modified with asciidoctor metadata for > when JBake bake the files, the files will have its metadata ported but on the > other hand, Github does not render the those correctly because of this > "~~~~~~" added to separate metadata and the content of the file. If you take > a look on this > [README.md](https://github.com/apache/tomee/tree/master/examples/applet) file > you can see that all content of the file is inside of a grey box making the > reading uncomfortable. > > It seems that the only way to add hidden metadata to a README.md file > supported by Github is adding the standard HTML comment. > > README.md file: > <!--- > title: Awesome Title > ---> > After baking: > title: Awesome Title > ~~~~~~
[...] > I'm wondering if would be nice to wrap the metadata with the standard HTML > comment and make the proper changes in tomee-site-generator project to handle > this and have both documentations with a nice layout and add the mandatory > metadata files to the [Github example > page](https://github.com/apache/tomee/tree/master/examples). I wonder if the simplest thing would be for us to change them from Markdown to Asciidoc. The long story short is that Asciidoc has a standard way to put meta-data for the generator and Markdown does not. The JBake guys sort of invented their own meta-data format for Markdown. It looks like if we use Asciidoc we can feed info to JBake and our own generation code and still keep Github happy: - https://github.com/apache/tomee/blob/master/docs/configuring-javamail.adoc - https://raw.githubusercontent.com/apache/tomee/master/docs/configuring-javamail.adoc Probably Asciidoc is a better format anyway, so maybe this is the push we need. -David
