Use Author Mode
How to activate author mode.
Although the primary function of Antora is to generate a site for publishing, it also serves as a tool for the author. By configuring Antora to use a local repository, you can preview local content, including content you haven’t committed.
Author mode is activated when you configure the playbook to use a local clone for one or more of the content repositories. Antora will use the repository as it is on your local machine instead of cloning it from its remote location. This scenario assumes you’ve already cloned a repository and want to incorporate it into the site generation.
To begin, create a folder named workspace in your project.
$ mkdir workspace
Switch to the newly created directory and clone one of the repositories:
$ git clone https://github.com/my-antora-demo/server-docs workspace/server-docs
Next, make a copy of your playbook file for local use. In the example below, antora-playbook.yml is copied and the new file is named local-antora-playbook.yml.
$ cp antora-playbook.yml local-antora-playbook.yml
Next, open your new playbook file and configure it to use the cloned repository instead of the remote repository. You can specify the repository either as a path relative to the playbook file or as an absolute path.
content: sources: - url: ./workspace/server-docs branches: HEAD (1)
|1||In author mode, you usually want to use the currently checked out HEAD of the local repository|
Build your Antora site using the new playbook file.
$ antora local-antora-playbook.yml
The contents of your local repository will be incorporated into the pipeline.
If your workspace directory is inside of your playbook repository, it is best to add it to your
You may be wondering what branches the generator selects when the repository is local and whether it will pick up your uncommitted changes. Here’s how a local repository is handled:
The repository contents on your local machine are used instead of the contents from its remote storage location.
The local repository is not updated from its remote storage location; Antora assumes the author will manage the repository (explicitly calling
git pullon the repository as needed).
Here’s how the branches are selected in author mode:
Both local branches and remote branches associated with the remote
If a local branch has the same name as a remote branch, the local branch is chosen.
The contents of the worktree get used in place of the files from the current branch. Aside from its name, the current branch is effectively ignored.
The current branch of your worktree must match the
branchesfilter configured on the
urlentry. If not, the working tree will be ignored. You can use the reserved HEAD value to ensure the current working tree is always used.
If you want to use multiple worktrees, simply clone the repository multiple times and configure multiple entries in the playbook.
You can use the
branches key to filter out the names of branches you don’t want.