-
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.
- 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
.
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 |
Use content as is with a |
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:
-
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.