paradox

paradox copied to clipboard

On Lagom, we generate docs as unstyled HTML snippets with an index, this then gets included in the main Lagom website source, which then puts the current Lagom theme around all the snippets from every version, and is able to do smart linking between versions (change the version and it goes to the current page in that version, but only if it exists, otherwise it goes to the index). By doing this, we ensure that if we update the Lagom website in future, we don't need to go back and regenerate the docs for old versions, and we don't end up in a situation like Akka where old versions use the old styling. This approach also avoids a situation like Play has where it has to support 3 different types of documentation because it generates the documentation on the fly from the original sources for all versions.

However, when we're developing the docs, we don't want snippets, we want them styled with navigation, so we need to be able to easily use one theme for development, and one theme when we generate the docs for inclusion in the Lagom website.

I am not that familiar with StringTemplate but it looks like it supports conditionals which could solve this issue by having one theme defaulting to dev mode and overriding when deploying.

paradoxTheme is already a setting in sbt paradox plugin, so I think this request can be implemented by implementing a content-only theme, and use that to build the site. We do switching out the theme already for Tech Hub as the guide docs are open source, but the theme used for the site isn't.