Antora Local Authoring

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.

1. install gulp globally

   >~/ $ npm install -g gulp-cli
   

2. install the dependencies in the root of your publishing project

   >~/ $ npm install --save-dev   antora-site-generator-lunr gulp-connect js-yaml
   

3. add gulpfile.js from this gist in the root of your publishing project
4. create a ./workspace folder and add to .gitignore

   >~/ $ mkdir workspace
   >~/ $ cat 'workspace/' >> .gitignore
   

5. create a local version of the playbook as local-antora-playbook.yml similar to this gist obviously edit the content sources will match your project
6. make local clones of your content projects into the correct directories under ./workspace¹

   >~/ $ git clone git@github.com:myaccount/mycontentproject.git workspace/mycontentproject
   

Editing content in author mode

1. 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 ../..

2. run the previewer

>~/ $ gulp

3. access the preview at https://localhost:5000
4. edit the content, refresh the browser to see changes

Pushing changes

1. stop the previewer

>~/ $ Ctrl-C

2. commit and push

   >~/ $ cd workspace/mycontentproject
   >workspace/mycontentproject/ $ git add -A && git commit -m"My lovely commit message"
   >workspace/mycontentproject/ $ git push
   

3. wait for the CI build and deployment to finish