This is a demo repository shows how to:
-
Using Antora and its extensions to collects AsciiDoc content from Git and content-generating scripts.
-
Publish the content on a website and use it also in other places like a PDF.
This is part of our presentation at FOSDEM 2023, which will be available as a recording after 2023-02-05.
See this blog post for all other resources (Slides, etc.)
Main application:
- Antora
-
The multi-repository documentation site generator for tech writers who ♥ writing in AsciiDoc.
The extensions:
- Antora Lunr
-
Create a search index for the site which is built with JavaScript can be served from a static site with no additional backend.
- Antora Collector
-
Generate content from outside of Git and use it like any other content.
Go to docs/content_v2/antora.yml to follow some bread crumbs how it has been configured.
- Antora Assembler
-
Take all pages of an Antora component
Go to playbook/antora-assembler.yml to follow some bread crumbs how it has been configured.
This is demo project some things are simplified which would be different in a real project:
-
Documentation (the content) and Playbook (the representation) usually live in different Git repositories.
The documentation can even be split out to multiple Git repositories which would be combined with one playbook per published website.
-
Different versions of the documentation live usually in different branches.
In this example the different versions are stored in different folders to allow for a simpler navigation.
-
The playbook folder contains an author-style playbook which uses the local checked-out repository’s worktree. This is idea for a local exploration and experimentation.
In a production setup, the real playbook uses a URL for the Git repository and can build different content/versions and use different attributes.
This project is being published via a GitHub action to a demo site.
Go to https://ahus1.github.io/antora-extensions-demo/ to see the result in your browser.
To build this project manually, see .github/workflows/docs-pages.yml or playbook/BUILDING.adoc
To find out more about Antora, see https://docs.antora.org/antora/latest/ for details.
As a project which uses Antora Collector and Antora Assembler, see the Eclipse Che Docs at https://github.com/eclipse-che/che-docs.
Copyright © 2023-present Alexander Schwartz and the individual contributors. Released under the Mozilla Public License Version 2.0 (see LICENSE).