Generating a CITATION.cff

A technote is a citable document: it has a DOI, authors with ORCIDs, a publisher, and a handle like SQR-000. GitHub surfaces that citation through a CITATION.cff file at the repository’s root — the “Cite this repository” button in the sidebar.

Documenteer generates that file from technote.toml, so the citation GitHub shows is the same metadata the technote itself is published with.

documenteer technote sync-cff

Run the command from the technote’s repository root, or point it elsewhere with the -d/--dir option.

technote.toml is the canonical source

CITATION.cff is fully managed: every run regenerates it from scratch, and the generated file says so in a comment on its first line. To change the citation, edit technote.toml and run the command again — an edit made directly to CITATION.cff is lost on the next sync.

Generation is deterministic and entirely offline. The same technote.toml always produces byte-identical output, so re-running the command on an up-to-date file changes nothing at all.

What gets generated

The Citation File Format allows only software or dataset as a file’s top-level type, and a technote is neither. The top level is therefore a stub describing the repository, and the technote itself is the file’s preferred-citation — a report reference, which is what GitHub renders and what carries the DOI:

CITATION.cff

# Generated by documenteer technote sync-cff from technote.toml — do not edit
cff-version: 1.2.0
message: If you use this technote, please cite it using the metadata from this file.
title: The LSST DM Technical Note Publishing Platform
type: software
authors:
  - family-names: Sick
    given-names: Jonathan
    orcid: https://orcid.org/0000-0003-3001-676X
    affiliation: Rubin Observatory Project Office
repository-code: https://github.com/lsst-sqre/sqr-000
url: https://sqr-000.lsst.io/
preferred-citation:
  type: report
  title: The LSST DM Technical Note Publishing Platform
  authors:
    - family-names: Sick
      given-names: Jonathan
      orcid: https://orcid.org/0000-0003-3001-676X
      affiliation: Rubin Observatory Project Office
  institution:
    name: Vera C. Rubin Observatory
  number: SQR-000
  doi: 10.71929/rubin/2570308
  url: https://sqr-000.lsst.io/
  date-released: 2026-08-24

Each field is read from technote.toml:

title

technote.title. A technote normally takes its title from the document’s own heading rather than declaring one in technote.toml; add a title field to the [technote] table so the citation names the document. Without one, the command falls back to the technote’s ID and says so.

authors

The [[technote.authors]] entries, in order. An author’s orcid is written as an orcid.org URL however technote.toml spells it, and the first of their [[technote.authors.affiliations]] supplies the affiliation — the Citation File Format records one affiliation per person.

number

technote.id, the technote’s handle within its series.

doi

technote.doi, normalized to its bare 10.NNNN/suffix form. A technote that has no DOI yet still generates a valid file; the doi field is simply omitted.

institution

technote.organization.name, the organization that publishes the series.

url and repository-code

technote.canonical_url and technote.github_url.

date-released

technote.date_updated, falling back to technote.date_created.

See also

Maintaining author metadata for keeping the [[technote.authors]] entries in sync with Rubin’s author database, which is where the ORCIDs and affiliations come from.

Checking the file in CI

The --check option compares the file on disk against what technote.toml generates, without writing anything:

documenteer technote sync-cff --check

It exits non-zero only when CITATION.cff exists and is stale. A repository with no CITATION.cff has simply not adopted the file, and passes.

documenteer technote lint reports the same staleness as TN106, using this same comparison, so a technote’s CI catches an unsynced file whether it runs the linter, this check, or both.

Running the sync as a pre-commit hook

Documenteer ships a technote-sync-cff pre-commit hook, so a technote repository can keep CITATION.cff current without remembering to run the command. Add it to the technote’s .pre-commit-config.yaml:

.pre-commit-config.yaml

repos:
  - repo: https://github.com/lsst-sqre/documenteer
    rev: 2.5.0
    hooks:
      - id: technote-sync-cff

The hook runs whenever technote.toml is staged and rewrites CITATION.cff in place, so a metadata change and the citation it implies land in the same commit. Set rev to the Documenteer release you want to pin to; pre-commit autoupdate moves it forward.