I think we should include some hints which markdown format is supposed to be used. Currently I guess it is only https://daringfireball.net/projects/markdown/syntax but in the future once flexmark-java is included it is ought to be http://spec.commonmark.org/0.28/ or whatever version is current and supported by flexmark-java at that point in time.
The whole section at https://sling.apache.org/ng/documentation.html#how-the-documentation-is-generated needs to be extended with at least the following information - the exact markdown syntax/spec with references - only markdown files should be used - how to locally generate the site For me the TOC limitation though is quite severe, because for larger pages like http://sling.apache.org/documentation/bundles/models.html the TOC is kind of crucial. Without it it is hard to find the right information. So to be honest I am not sure we should already migrate before the TOC support has been added. It seems that the support for flexmark-java is only supposed to land in JBake 2.7.0 which is the version after the next version (so rather far away in the future). Have you guys considered switching from MD to AsciDoc which already has native TOC support in JBake. Don't know how feasible it is to migrate the existing MD files though... Konrad > On 27. Sep 2017, at 10:08, Carsten Ziegeler <cziege...@apache.org> wrote: > > +1 > > > Stefan Seifert wrote >> +1 >> >> small issues that may still be present can be fixed later, i think we have >> no showstoppers. >> >> stefan >> > -- > Carsten Ziegeler > Adobe Research Switzerland > cziege...@apache.org
