Hi , I agree .
So is best convert to asciidoc the existence and the new add in format asciidoc . -- *Daniel Dias dos Santos* Java Developer SouJava & JCP Member GitHub: https://github.com/Daniel-Dos Linkedin: www.linkedin.com/in/danieldiasjava Twitter: http://twitter.com/danieldiasjava Em dom, 9 de dez de 2018 às 15:04, David Blevins <david.blev...@gmail.com> escreveu: > 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 > >
