On Wed, 2017-09-27 at 10:33 +0200, Konrad Windszus wrote: > 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/mark > down/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#h > ow-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).
My personal opinion is that migrating to git and away from the ASF CMS is already a win, since it becomes much easier to control the overall behaviour of the website. As for the TOC, we can have a stop-gap solution with something like [1] until we get proper support in JBake. > 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... I think that would be another big project, if we decide to do that. It already is quite involved to keep the two systems in sync, adding a conversion step in the meantime would make it even harder. Thanks, Robret [1]: https://github.com/nghuuphuoc/tocjs > 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 > >
