@opendevise/antora-object-storage-extension/README.md

An Antora extension that diverts lfs objects to a dedicated branch of the playbook repository and serves them from that location; reduces build time when generating the site and upload time when publishing the site. Designed for use with GitLab CI and Git

# Antora Object Storage Extension

An [Antora](https://antora.org) 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.

```console
$ git config --global user.name "Publisher"
  git config --global user.email publisher@example.com
```

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

```console
$ 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)

   ```bash
   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

```console
$ 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.](https://opendevise.com) and the [Antora Project](https://antora.org).

Use of this software is granted under the terms of the [Mozilla Public License Version 2.0](https://www.mozilla.org/en-US/MPL/2.0/) (MPL-2.0).