Writing content for your Antora site
In the note about publishing I described how the final published site gets built.
However in reality you will want to preview your work locally before you push to the published site.
Antora supports an author mode of working where it builds a site based on local clone(s) of the content project(s) (as opposed to fetching a specified branch or tag from the published repository/repositories at build time.)
A gulp script is available to produce a local version of the website that rebuilds each time the content is updated.
Configuring author mode in a project
If you are working with an existing documentation project this step will have been done, but it’s useful to know how to configure.
- install gulp globally
>~/ $ npm install -g gulp-cli
- install the dependencies in the root of your publishing project
>~/ $ npm install --save-dev antora-site-generator-lunr gulp-connect js-yaml
gulpfile.jsfrom this gist in the root of your publishing project
- create a
./workspacefolder and add to
>~/ $ mkdir workspace >~/ $ cat 'workspace/' >> .gitignore
- create a local version of the playbook as
local-antora-playbook.ymlsimilar to this gist obviously edit the content sources will match your project
- make local clones of your content projects into the correct directories under
>~/ $ git clone firstname.lastname@example.org:myaccount/mycontentproject.git workspace/mycontentproject
Editing content in author mode
- make sure you have latest version of your content and open an editor (e.g. VS Code)
>~/ $ cd workspace/mycontentproject >workspace/mycontentproject/ $ git pull origin master >workspace/mycontentproject/ $ code . >workspace/mycontentproject/ $ cd ../..
- run the previewer
>~/ $ gulp
- access the preview at
- edit the content, refresh the browser to see changes
- stop the previewer
>~/ $ Ctrl-C
- commit and push
>~/ $ cd workspace/mycontentproject >workspace/mycontentproject/ $ git add -A && git commit -m"My lovely commit message" >workspace/mycontentproject/ $ git push
- wait for the CI build and deployment to finish
this assumes you have direct access to the content. In a more complex environment you may need to work with forks of the content repositories and submit changes via pull request. ↩︎