lightbend/paradox

Guidance on how to use includes

raboof opened this issue · 2 comments

raboof commented

With the 'includes' feature, it seems to make sense to have .md files whose only goal is to contain snippets for inclusion in other pages.

It seems to make sense to put those .md files in src/main/paradox as well, but on the other hand we wouldn't want such an .md file to turn into a separate .html page. This concern is further highlighted because it also shows up as a 'root' in the paradoxRoots feature.

Should we choose a naming convention (_includes/*?) and exclude any .md files under that path by default?

raboof commented

I think we should support a directory like src/main/paradox/_includes for .md files that don't get rendered to standalone pages, but are available to be included in other pages.

  • 👍1
jroper commented

In my case I just used includes, and manually excluded it this way:

https://github.com/lightbend/openshift-deployment-guide/blob/master/build.sbt#L34-L35

We could create such a convention and also automatically exclude it in the paradox plugin.

  • 👍2