Antora Git Large File Storage (LFS) Extension

An Antora extension that converts a remote content source marked as lfs enabled with a local worktree with git lfs objects inflated.

Overview

Antora (as of 3.1.x) can only process git lfs objects if they are already inflated in a worktree of a local content source. Antora itself doesn’t support inflating git lfs objects. If these objects aren’t inflated, Antora will publish the pointer file instead of the object referenced by that pointer.

This extension provides a short-term solution for using repositories with git lfs enabled until support is added into Antora. The extension uses the native git command (instead of the built-in git client) to clone content sources marked as lfs enabled. If the repository has already been cloned, the extension will pull updates if the runtime.fetch playbook key is enabled. The extension then replaces the reference to the remote repository in the playbook with the local one. The cloned repositories are stored in the value of the worktree_dir configuration key, which defaults to a folder in Antora’s cache.

❗ IMPORTANT
Currently, this extension only works on the first commit or first branch configured on a content source. Other commits and branches will be unregistered. If the content source has multiple commits or branches, each commit or branch that contains lfs objects must be represented by a separate entry in the playbook.

📌 NOTE
If the content source is a local repository (i.e., a git worktree), the extension will still read the lfs files from that respository, but it will otherwise treat it as read only.

Usage

content:
  sources:
  - url: https://githost/example/repo-with-lfs.git
    lfs: true

$ npx --package antora --package @opendevise/antora-git-lfs-extension \
  --extension @opendevise/antora-git-lfs-extension antora-playbook.yml

Configuration

The extension supports the following configuration keys:

| Name | Type | Default | Description | | --- | --- | --- | --- | | workspace_dir | Directory path (String) | A folder named content-with-lfs in the Antora runtime cache dir. | The directory into which git lfs repositories will be cloned. |

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).