001 Antora is used as Site Generator
-
date: 2024-06-23
-
status: accepted
Context and Problem Statement
To be more accessible, this repo should have a nice documentation like the original. Every Recipe should be documented, but there should also be How-Tos. The documentation of the single recipes should be structurally similar to the official recipe catalog. For that we need a static site generator, that can host our page on GitHub pages.
Decision Drivers
-
I don’t know much about frontend stuff, don’t want to invest time to learn
-
I don’t have much time for maintenance
-
I know AsciiDoc would like to use it again
Decision Outcome
Chosen option: "Use Antora", because it is something new but not too different from docToolchain.
Consequences
-
Good, because I can generate Docs with a modern tool
-
Bad, because
@DisplayNameand@Descriptionof the recipes are in Markdown, need to be converted to AsciiDoc now. (see also madr/002_DisplayName_and_Description_are_given_in_Asciidoc.adoc) -
Bad, because customizing the UI will be difficult.
Pros and Cons of the Options
Antora
https://antora.org/ Git friendly, AsciiDoc based documentation framework.
{example | description | pointer to more information | …}
-
Good, because seems actively maintained
-
Good, because sleek appearance
-
Good, opportunity to learn something new
-
Bad, because unclear how much effort to get into it
-
Bad, because no dark mode[1]
DocToolChain
http://doctoolchain.org/docToolchain/v2.0.x/index.html Generic framework that can convert all sorts of Artifacts (such as AsciiDoc files) to a Microsite or other destinations (Confluence, Word, …)
-
Good, because I already know it
-
Good, because matured, feature complete
-
Good, because I don’t need to learn JavaScript
-
Bad, because no dark mode either
-
Bad, because does not seem actively maintained (still new releases, but many open issues)
-
Bad, because uses old tech stack
-
default UI (docsy) looks a bit old
-
based on JBake (last release 2021-05-15, Release candidate out for over a year…)
-
customization possible with Groovy, better than learning JavaScript but not 'hip' either.
-
What OpenRewrite uses
I haven’t looked to deep into what they are using. It seems to be a custom solution (actually based on GitBook).
-
Good, because nice opportunity to get familiar with GitBook
-
Bad, because it may give the false impression that I am affiliated with them or pretend to be.
-
Bad, because their solution does more than I need ("AI Search")
-
Bad, because probably tough to keep up maintaining my own fork of their docs.