Antora Object Storage Extension

An Antora extension that stores attachments in a dedicated branch of a git repository with git lfs enabled instead of publishing them with the site. The extension automatically generates redirects to route attachment URLs to the backing storage. The URL of each attachment remains unchanged.

Overview

If your site has a lot of large attachment files, this can place strain on the build and publishing process for the site. To alleviate this problem, you can siphon off attachments to a warehouse and reroute incoming requests to those files. By doing so, the amount of memory required for building and publishing the site is dramatically reduced since what remains is mostly just HTML pages and images.

This extension uses a git repository as the attachment warehouse (by default, the objects branch of the playbook repository). All attachment files are stored as git lfs objects in the objects branch. The secondary benefit of using this approach is that only files that have been modified need to be pushed (git automatically tracks and manages changes).

❗ IMPORTANT
The extension currently assumes you are running Antora on GitLab CI and GitLab Pages. The extension relies on GitLab Pages’ redirect engine to reroute the request to the raw attachment file in the git repository. Changes will be needed if you are using a different CI environment.

Usage

Configure git

In order for the extension to use git to commit and push changes to the object storage, you’ll need to configure the git user.

$ git config --global user.name "Publisher"
  git config --global user.email [email protected]

Replace the values with the ones suitable for your repository. If you are running in GitLab CI, you can use the predefined environment variables.

$ git config --global user.name "$GITLAB_USER_NAME"
  git config --global user.email $GITLAB_USER_EMAIL

Prepare storage branch

You’ll need to set up an orphan objects branch on the playbook repository before using the extension the first time.

1. Create orphan branch (optional)

   git checkout --orphan objects
   git rm -rf .
   echo -e '* text=auto eol=lf\n' > .gitattributes
   git add .gitattributes
   git commit -m 'init object storage branch'
   git push origin objects

   💡 TIP
   You can avoid this step by adding create: true to the extension’s configuration.

2. Enable git lfs on repository

3. Create project access token with write_repository scope and Developer Role and define as PUSH_ACCESS_TOKEN CI variable

The extension will only run if the CI_PROJECT_URL environment variable is set. The value of this variable must be the URL of the playbook repository. This variable is set automatically when running in GitLab CI.

Run

$ npx --package antora --package @opendevise/antora-object-storage-extension \
  --extension @opendevise/antora-object-storage-extension antora-playbook.yml

To be most efficient, this extension should be used with @opendevise/antora-git-lfs-extension, which populates the oid of lfs objects aggregated from the content sources.

Configuration

The extension supports the following configuration keys:

| Name | Type | Default | Description | | --- | --- | --- | --- | | branch | String | objects | The name of the branch to use for object storage in the current repository. | | create | boolean | false | Whether to create the orphan object branch on the current repository if it does not yet exist. | | readonly | boolean or strict | false | In readonly mode, the object storage is only used as a cache. No attempt is made to update it. When readonly is strict (string), the object storage cache will not be created (cloned) or updated (fetched). |

Remember that the extension will only work if both the CI_PROJECT_URL and PUSH_ACCESS_TOKEN environment variables are set when running Antora.

Copyright and License

Copyright (C) 2025-present OpenDevise Inc. and the Antora Project.

Use of this software is granted under the terms of the Mozilla Public License Version 2.0 (MPL-2.0).