@opendevise/antora-git-lfs-extension v1.0.1

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 branch configured on a content source. If the content source has multiple branches, each branch must be represented by a separate entry in the playbook.

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:

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