+1 on moving to asciidoc
Bruno Baptista
https://twitter.com/brunobat_
On 09/12/18 17:27, Daniel Dias Dos Santos 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 <[email protected]>
escreveu:
Great topic. I actually hadn't noticed till you pointed it out!
On Dec 9, 2018, at 8:48 AM, Jose Henrique Ventura <
[email protected]> 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
