Example of adding Antora local author preview

Making it easier for developers to contribute to #docsascode by adding Antora local preview tools to code repos

In Antora Local Authoring I described how the author mode configuration could be used to manage your local copy of a documentation site.

Where I work we have been running a couple of internal documentation sites for 2 years, the largest of which references nearly 30 source repositories. Although I drove the initial work I am always looking for ways to encourage colleagues to get involved with writing documentation, especially if they are contributing code changes to one of the systems or services that are documented.

One of the barriers has been the inability to easily preview documentation changes when in the context of a specific code repository. Since one of the goals of #docsascode is to manage the documentation for a feature as you write that feature this has been a major impediment.

The change I have started implementing from today is to add the minimum extra to each code repository to allow developers to run a local preview copy of the documentation.

  • additional dev dependencies
  • an additional documentation component to act as a local site entry point, with links to the other components
  • an Antora local playbook
  • a Gulp configuration to run antora agaisnt the local playbook and host a development server

Running the preview is as simple as:

And the result looks like this:

Example repository running in author mode preview
Example repository running in author mode preview

(internally we insert our own branded Antora UI so that the preview looks more like the final result)

The simplest example is in a repository on Github.

Proactive application of technology to business

My interests include technology, personal knowledge management, social change