Antora is a fairly new open source static site generator, aimed at Technical Authors who prefer writing in AsciiDoc than Markdown.
SitePoint describes a static site generator as:
A compromise between using a hand-coded static site and a full CMS (such as WordPress or Confluence). You generate an HTML-only website using raw data (such as Markdown or AsciiDoc files) and templates.
The attraction of using a static site generator is it’s less complicated to manage than a CMS (with their databases, scripts and plugins), the websites are fast, and you can host the website on pretty much any platform that offers (free) file storage.
Lightweight markup languages are different from word processors like Microsoft Word, in that you can just open up a text file, write content for your document, using a particular formatting set of standards for doing things like headings and lists, and save it with the relevant file extension.
AsciiDoc is a lightweight markup language that is based on an XML standard. This means you can mark up the text semantically for different audiences, different versions, and other conditions – an area where Markdown struggles.
Antora enables you to store documentation in multiple repositories (or for example, GitHub). It can retrieve and aggregate all the content from them to assemble a documentation site. This means the teams that maintain the content can use their own administration and release schedules for their individual sections.
However, there’s a group of people with simpler requirements. They might want to use a static site generator to create an intranet. In that situation, the content usually needs to be stored on internal servers, rather than on GitHub. To help people in this situation get started, Daniel Mulholland has created an example that can generate an Antora site from AsciiDoc files stored locally. on a computer. It’s available on GitLab for you to clone or download:
If you wanted to take a look at Antora, this simple repository might be a good starting point.
Leave a Reply