Replace your wiki with a documentation site

Bonjour, la version française de cet article peut être lue sur dev.to

No matter what your IT project is, there will always be a need to store some documentation.
The choice to use a wiki is quite common in the corporate world.

Let's talk about you, developer on one of these programs, is documentation of your different projects managed by an easily accessible and editable wiki?

If you look at the content of this wiki, you will probably find:

• Pages with sections who still need documentation,
• Pages with incorrect information,
• Deprecated pages,
• Pages only useful for one team or another,
• Pages with documentation on a feature still in development.

So you wonder how to make it easier for people working on different projects.

At this point, the principle of documentation as code seems to be the solution to your needs.

You embark on the adventure of documentation as code

Seeing the documentation as code as the sources of the program is interesting.
You want to replace your current wiki with a project dedicated to documentation, and allowing you to make code review on these changes.
But that only corrects part of the problem, you only replaced wiki pages with files written in another format like:

• the Markdown format,
• the Asciidoc format.

Due to its simple and accessible syntax, Markdown is one of the most popular formats, especially on sites like github or gitlab, but it is too simple for further documentation.

Asciidoc is more interesting, allowing to be more expressive with your documentation.
The associated tool Asciidoctor provides useful features as well as integrations such as diagram generation with plantuml.

You therefore choose to write the Asciidoctor documentation in each of your projects.
This allows you to deliver the documentation at the same time as the associated code.

Even if your program consists of a set of projects, each with its own documentation, you want to keep a single site to access them.

The people behind Asciidoctor have recently released an aggregated documentation site generator: Antora in a stable version (1.0.0) to the open-source community.

You create your new documentation site with Antora / Asciidoctor

A site generated by Antora is composed of three elements:

• Your projects that contain their documentation,
• The playbook that configures the generation of the documentation site,
• A UI that defines the visuals of your site (the default one will be appropriate).

To be used by Antora, a project must respect a file structure

./docs
├── antora.yml
└── modules
    └── ROOT
        ├── _attributes.adoc
        ├── nav.adoc
        └── pages
            ├── _attributes.adoc
            └── index.adoc

You set up documentation as code on your projects

So you apply yourself to put it up on:

• Your APIs (api A, api B, api C)
• Your tools (build tools),
• Your development guide (guidelines).

The documentation in Asciidoctor format is available in the docs folder.

It is not necessary to use this tree for guideline, which is only a documentation project.

You are preparing to generate your documentation site

So you create a specific project to store the playbook.

site:
  title: "Romain Lespinasse // Docs"
  start_page: guidelines::index
  url: https://rlespinasse.github.io/docssite
content:
  sources:
  - url: https://github.com/rlespinasse/api-a.git
    branches: master
    tags: v*
    start_path: docs
  - url: https://github.com/rlespinasse/api-b.git
    branches: master
    tags: v*
    start_path: docs
  - url: https://github.com/rlespinasse/api-c.git
    branches: master
    tags: v*
    start_path: docs
  - url: https://github.com/rlespinasse/buildtools.git
    branches: master
    tags: v*
    start_path: docs
  - url: https://github.com/rlespinasse/guidelines.git
    branches: master
ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true
  output_dir: ui-bundle
  supplemental_files: ./supplemental-ui
output:
  dir: ./docs

The content of the playbook site.yml defines:

• the related information to the site itself via site:,
• the definition of content via content:,
• the theme of the site via ui:,
• The build folder via output:.

The official documentation does not refer to it because it is a development still experimental but you set up the navigation bar to add the useful links via a header-content.hbs file in supplemental-ui/partials/.

Other template files are available for replacement in Antora Default UI.

You generate and deploy your new documentation site

You can install antora via this guide or use the docker image via the docker run -v `pwd` command: / antora --rm antora / antora --stacktrace site.yml (where site.yml is the playbook)

The playbook defines the docs folder to make your new documentation site available.

For example, to make it accessible on Github, you deploy it via the Github Pages of your docssite project.

The platform will automatically expose the contents of the /docs folder to https://rlespinasse.github.io/docssite.

You make others benefit from the new documentation site

From now on, people working on the program will be able to add, create, and maintain documentation of each project very easily. Your new documentation site gives the access to all these pages.

The site docs.antora.org uses the Antora project itself.

Thanks to Aurélien Allienne, Antoine Méausoone, Tanguy Baudrin, and Tony Proum for reviewing the article.
Thanks to Aurélien Allienne, Guillaume Mantopoulos for the review of the translation from french to english of this article .