Why talking about Antora and AsciiDoc?
In one of our previous meetups of the Continuous Documentation Regulars some participants asked to hear more about Antora, “the documentation site generator for tech writers who 🧡 writing in AsciiDoc”. So this is what we did in this meetup.
What we did: Intro plus extensive Q&A
I started with a brief 15 minutes intro. The site of the IntelliJ plugin for AsciiDoc served as an example for some live coding.
After that we dived into a discussion. Thanks and kudos to all participants who joined and made this a success with their questions and answers — this wouldn’t be possible without you!
Find below a recording of the session. Get in contact and share your feedback with me!
Scroll down a bit further in this blog post to find the show notes linking to content referred to in the recording.
Recorded Meetup
Thank you, Ralf Müller, for asking questions and reading out participant’s questions from the chat while I shared my screen. For all other participants we agreed that they will not be on the recorded for the video to remain GDPR compliant.
Questions and Answers
- What repositories did you use in the demo?
The demo used the repositories of the IntelliJ AsciiDoc plugin. See the contributors guide for writers to find your way around. It contains the links to the GitHub repositories shown during live coding.
I also showed the Debezium documentation (see here for the source on GitHub).
- How can I sell Antora to my manager?
Go to antora.org and scroll down. No kidding! All the information you look for is below the fold.
My key point for Antora is the ability to link between pages and versions. This is great for writing versioned technical documentation. Plus everything I like from AsciiDoc, for example nested lists, tables, admonitions and including code snippets.
- How can I get help when working with Antora?
The docs for Antora cover most of the main questions.
Antora’s Gitter chat for users is the place for beginner’s and advanced questions. Go to antora.org, select Docs › Community › Chat (Users) or use this direct link.
The Write the Docs community is a friendly place for everyone involved in writing docs. Their Write-the-docs-chat-on-Slack is open for anyone to join. There is no specific channel for Antora, but the channel #asciidoc is an excellent place to meet.
Use both places, the Antora Gitter chat and The Write the Docs Slack, to search for paid consulting.
- What is needed to host an Antora documentation site?
The output of Antora is a static HTML site. It can be hosted on any web server. The example presented uses Netlify to host the site as it offers nice automation around the build process. The same result can be achieved with a hosting service like GitHub Pages, GitLab Pages or an Apache httpd server.
The hosting service can provide authentication and authorization to restrict access to the content. For example: GitLab Pages can restrict access to only project members.
- What options for Antora site search are available?
- Algolia Docsearch: Cloud based service.
Example: Antora docs site. - Coveo JavaScript Search Framework: Cloud based service.
Example: Mulesoft docs site. - Lunr: Self-hosted client side JavaScript; will work with any static intranet or internet site.
Example: IntelliJ AsciiDoc plugin's docs site.
Antora provides a sitemap.xml that a public or enterprise search engine can use to index the pages.
- Algolia Docsearch: Cloud based service.
- How can I include diagrams?
Asciidoctor Kroki has an Antora integration. It allows rendering of images at build time or when rendered in the browser.
Kroki is open source. There is a public cloud instance. As it is ready to run in containers, organizations can host private instances when needed.
- How can I include mathematical formulas?
- Using client-side JavaScript, this can be achieved using MathJax.
- How can I include Antora in a Maven based build?
Antora is based on Node and JavaScript. The maven-frontend-plugin can serve as a wrapper for any Node.js/npm/Yarn based build.
There is a blog post “Building Antora with Maven” by Abel Romero describing the setup step-by-step. It also includes an example code repository on GitHub.
- How can I have code examples in different languages side-by-side in separate tabs?
An example for this is available in the Couchbase documentation for contributors.
Look for the
tabs-block.jsthat is part of Couchbase’s Antora playbook. The code is also present in the Antora extensions repository. (As it is a different repository, it might be a different version.)
How to continue learning
Besides the Antora docs I can recommend:
- For a brief walk-through or refresher of Antora’s concepts and capabilities the blog post “Awesome Antora: Migrate from GitBook to Antora” by Guillaume Grossetie.
- As a minimal example, Antora has a demo comprising three repositories: two with content, one that provides the playbook to create the site.
- The documentation for the IntelliJ AsciiDoc plugin is always happy for contributions and helps contributors in this effort. Follow the contributors guide for writers to find your way around.
- The Couchbase Documentation has an extensive chapter “Contributing to the documentation” that covers setting up a workspace and testing the build locally.
Fin
That’s all folks! I hope you enjoyed the meetup and its content. Get in contact to share your feedback or tell others about what you found here by sharing the link. Join the Continuous Documentation Regulars meetup to hear about upcoming events.