Metadata should not prevent rendering of markdown in 3rd party editors

[kwin]

To allow using WYSIWYG MD editors or the preview functionality of the GitHub editor the metadata should be placed in the markdown in a way that doesn't make it invalid. Several options come to my mind:

1. Put metadata in another file with the same name but another extension (like .prop)
2. Put metadata inside HTML comments
3. Place it in link labels like described in https://stackoverflow.com/a/20885980

[kwin]

Currently the GitHub editor's preview completely chokes on the metadata as can be seen in https://github.com/apache/sling-site/edit/master/src/main/jbake/content/documentation/development/release-management.md.

[jbaron]

Just my 2 cents, I got same problem with the markdown editor in IntelliJ IDEA.

But then found out I can define a different separator. So adding the following to jbake.properties worked out for me and the markdown is now correctly rendered in IDEA (and of course up date your content files to use the new separator)

header.separator=~~

I still think a good idea by default to use a separator that interferes less with editors.