Keycloak docs with Antora Proof-of-Concept

What to see here

• How the existing docs of the new Quarkus guides and classic guides can be migrated to Antora.

• How a minimal Antora site could look like.

• How Antora Assembler can create a single AsciiDoc file that can then be processed downstream; as a placeholder Asciidoctor PDF creates a PDF from the source.

  Download the single AsciiDoc source and the PDF created by Antora Assembler from the start page.

Content of the repository

antora

Folder with templates for the site and Antora’s configurations

This should eventually be moved to its own Git repository as it is independent of the modules and their releases.

Enabled with antora-assembler which will create one big AsciiDoc file per component in the build folder.

docs-original

The server-guide and operator-guide in the new format, and the admin-guide in the old format. Taken as a snapshot from the current development branch. For the guides, the freemarker templating has been completed.

doc

Documentation re-organized documentation from above put into the Antora folder structure. The update of internal references is complete for all guides.

To see what has changed, compare the files in the two folders doc and docs-original.

Process old vs. new Process

The following process is completed for each Antora component (new process) or guide (old process).

Task	New process	Old Process
Writing content	AsciiDoc using Antora component structure. (link to git)	File structure inspired by modular writing. (link to git)
Publishing upstream	Antora creating multi-page HTML site. (link to web site)	Maven with AsciidoctorJ, creating a single HTML file. (link to web site)
Content for downstream	Create a single AsciiDoc file using Antora Assembler and adding master.adoc and master-docinfo.xml.	Use content as is with a master.adoc and master-docinfo.xml file.
Downstream processing	ccutil/Pantheon creating HTML and PDF. (ZIP file with input from previous step and generated content) (website output ccutil)	ccutil/Pantheon creating HTML and PDF.

Concepts and Questions

Concepts:

• Antora components contain the version, and it can have multiple modules that share the same version.

• A navigation is based on the component and spans multiple modules

• A link from one component to another component that doesn’t specify a component version will link to the latest release of that component.

  To link to the same version of a component, use for example xref:{page-version}@guides-server::importExport.adoc[]

• Antora Assembler will create on AsciiDoc file per component; alternatively it can also create on AsciiDoc file per navigation item in a component.

Questions:

• Should all artifacts that share the same version number (Keycloak server and Keycloak operator) be in the same component?

Concept:

• When stripping the .html at the end of an URL, there can be either a page or a folder with that name.

Question:

• How show the parent page be named compared to the folder? As an itermediate solution, all parent pages received the -all suffix.

Concept:

• All files inside pages are rendered as HTML and should be references in nav.aodc

Question:

• Decide which includes should be converted to pages, and which should be moved to partials.

Concept:

• Antora assembler will adjust all xref:[]s within a component. Those to other components are not adjusted, and will also not show the page title.

Question:

• Can this be post-processed in the resulting AsciiDoc file, and can linting ensure this in the writing phase?

Concept:

• Antora assembler assigns an ID to each page before adding it to the document, and uses this in xref:[]s in the document. It also applies this to any partial that is being included.

Question:

• This conflicts when a page contains already an ID with the topmost heading (like [id="proc-registering-new-user_{context}"]) and Antora will then have both in the result ([#assembly-managing-users:::proc-registering-new-user,id=proc-registering-new-user]). The second ID is then ignored when rendering the result in Asciidoctor, and this doesn’t cause any ripple effects.

  Suggestion: Change to the ID type of [#xxx]. Assembler will then replace the reference with a new reference. A short test showed that attributes in references don’t work well. In the case given above, the reference should be changed to [#proc-registering-new-user].

  In general, those IDs should only be added when referenced somewhere else. The references already contain the file name for the parents, the file name of the include and the name of the component, so they can be assumed to be unique and stable as a change of the heading will not change the reference in the generated HTML when uses would bookmark it. A {context} adds complexity and no additional value.

• Assembler doesn’t support having a custom ID in headings in the target file. If that would be necessary, post-processing would be necessary. This would make the process more fragile, so I currently won’t recommend it.

Concept:

• An IDE like IntelliJ can list to an Author where a partial is being used.

Suggestion:

• Comments like Module included in the following assemblies: are then obsolete and should be removed. This information is available via the IDE, and tends to be outdated soon when put in a comment.

Concept:

• Assembler passes all attributes from the Antora component descriptor and playbook to the command line of the PDF generation.

Suggestion:

• By wrapping the command, the attributes can be saved into a separate file for the downstream process.

Observation:

• The PDF generation is quite slow.

Suggestion:

• The creation of the AsciiDoc content is fast, and for the downstream docs the PDF generation should be disabled.

Concept:

• The file name of a page is also the end of a URL in Antora

Suggestion:

• The pages should not contain a modular writing prefix like assembly_.

Concept:

• The first lines below a title (lines starting with a single =) are attributes to the title, not text.

Requirement:

• Create a blank line after each title and before everyhting else (like, for example, a [role="_abstract"])

Concept:

• All xref:{page-version}@guides-server::.. refernces work in Antora. But as they can’t be converted by Antora assembler as they are outside references, those need to be replaced with regular link (possibly via sed, see GitHub action).

Suggestion:

• To have a proper text replacements, provide the full link text in the brackets.

Todos for a real site

• Consider Algolia for a hosted search service instead of client-side JavaScript search, as the index would overwise grow too big.