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:
npm installnpx gulp- visit http://localhost:5000
And the result looks like this:
(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.
