Hi Daniel, Yes, as a second option would be better to convert the files to asciidoc.
https://github.com/github/markup/blob/master/README.md Best Regards, José Henrique Ventura. ‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐ On Sunday, December 9, 2018 5:27 PM, Daniel Dias Dos Santos <daniel.dias.analist...@gmail.com> wrote: > 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 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. > > > > 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
