CV settings reference (cv.yaml)

adsfolio cv generates publication-list fragments for CV workflows from ADS query results.

A YAML file (cv.yaml) configures the command.

Output formats:

• LaTeX output (primary)

• Markdown output

• user-defined templates for any text format: LaTeX, HTML, Markdown, plain text, or another format you write

Content options:

• multiple rendering styles

• marker categories by bibcode

• status overrides for accepted/submitted preprints

The desktop application has the same features in Tools → CV Generator…. See CV Generator. The window and the command share cv.yaml in the ADSfolio configuration folder.

Command surface

adsfolio cv init
adsfolio cv generate --config cv.yaml
adsfolio cv show-styles

Common generation overrides:

adsfolio cv generate --config cv.yaml --dry-run
adsfolio cv generate --config cv.yaml --format markdown --style detailed
adsfolio cv generate --config cv.yaml --author-format 'ads_custom:%3.2l'
adsfolio cv generate --config cv.yaml --output out/publications.tex

--dry-run still queries ADS and renders the result. It prints to stdout instead of writing a file.

--format selects a renderer but does not rewrite an existing configured filename. Therefore, supply --output out/publications.md when you switch a LaTeX configuration to Markdown.

adsfolio cv resolves relative output.dir paths against the YAML file’s directory. An explicit CLI --output is relative to the current working directory.

ORCID behavior:

• adsfolio cv init reads defaults from your adsfolio set profile.

• If profile ORCID exists, cv init enables ORCID matching by default.

• Use adsfolio cv init --no-orcid to disable that default at config creation.

Config schema

Top-level sections:

• author

• format

• markers

• status

• output

Required field:

• author.query

author

Field	Type	Description
query	string	ADS Solr query used as base query
orcid	string	ORCID identifier used when use_orcid is true
use_orcid	bool	Whether to add orcid_pub:"<orcid>" constraint
debut_year	int/null	Optional lower bound for publication year
retire_year	int/null	Optional upper bound for publication year
exclude_bibstems	list[string]	Bibstems to exclude via appended bibstem:(- X) clauses
first_author_prefix	string	Lowercase prefix used to classify first-authored papers
me_target	string	Name token used by format_author_list_cv() highlighting
me_display	string	Display name metadata for user context

format

Field	Type	Description
output	latex | markdown | template	Renderer target
style	compact | detailed | bibcode-first	Render style
n_max_authors	int	Author list truncation threshold
n_min_authors	int	Minimum shown before et al.
n_me	int	Ensure highlighted author appears within threshold
author_sep	string	Author separator
me_fmt	string	.format() template for highlighted author
author_format	string	cv_default or ads_custom:<format>

template

adsfolio cv uses this section when format.output is template. Each part is text with {name} placeholders. adsfolio cv replaces only the names below. Other braces stay as written, so LaTeX needs no doubled braces: \textit{{title}} becomes \textit{Dust in comet atmospheres}. A misspelled placeholder, such as {titel}, stays in the output unchanged.

Field	Description
preset	Optional starting point: latex, markdown, html, or text
header	Once, at the top
section	Before each section (First-authored, then Co-authored)
entry	Once per publication
section_end	After each section, for example </ol>
footer	Once, at the end
escape	latex, html, or none: how ADSfolio escapes ADS text
group	true (default) for First-authored and Co-authored sections. false for one section, Publications, in the original order

A preset fills every part, escape, format.me_fmt, format.author_sep, and output.filename. Keys that you write replace the preset values.

Placeholders:

Part	Placeholders
header, footer	{me}, {date}, {total}, {first_count}, {co_count}
section, section_end	{section}, {count}
entry	{index}, {authors}, {title}, {year}, {journal}, {volume}, {page}, {venue}, {bibcode}, {url}, {doi}, {citations}, {n_authors}, {status}, {markers}

{venue} joins journal, volume, and page and leaves out empty parts. {authors} applies format.me_fmt to your name, for example <b>{}</b> in HTML. ADSfolio escapes text from ADS for the escape target. It never changes text that you write: the template, me_fmt, author_sep, status, and marker symbols. With escape: none, ADS text is plain Unicode without markup.

format:
  output: template
template:
  preset: html
  entry: '<li>{authors} ({year}). <a href="{url}">{title}</a>. {venue}.</li>'

Template output does not add the journal or marker legends. Write them in the footer if you need them.

markers

markers is a map of arbitrary marker categories:

markers:
  highlight:
    symbol: "\\textbf{\\color{myblue} \\small \\ddagger}"
    description: "Selected publications"
    bibcodes:
      - "2024A&A...684A..80B"

Each category includes:

• symbol (string)

• description (string)

• bibcodes (list[string])

status

status maps bibcode to free-text status string:

status:
  "2025arXiv251207318L": "ACCEPTED by \\textbf{ApJL}"

output

Field	Type	Description
dir	string	Output directory
filename	string	Output filename
journal_legend	bool	Append bibstem-to-journal legend
latex.list_env	itemize | enumerate	LaTeX list environment
latex.left_margin	string	List left margin option
latex.item_sep	string	List item separation

ADS query build behavior

At runtime, adsfolio cv builds the query as follows:

1. include orcid_pub:"<orcid>" when author.use_orcid is true

2. include year:[start TO end] when you set debut_year/retire_year

3. include author.query

4. append bibstem:(- <value>) for each author.exclude_bibstems item

Rendering behavior

Classification

adsfolio cv splits fetched ADS docs into:

• first-authored: first_author starts with first_author_prefix

• co-authored: all remaining docs

Marker and status application

adsfolio cv:

• appends marker symbols for bibcodes listed under each marker category

• appends status text from status[bibcode] when present

• tracks and marks non-peer-reviewed documents (NOT REFEREED, excluding arXiv)

Author formatting modes

adsfolio cv supports two author formatting modes:

• cv_default: uses local format_author_list_cv() with n_max_authors, n_min_authors, n_me, me_target, and me_fmt.

• ads_custom:<format>: requests author formatting from the ADS/SciX export API for custom formats (/export/custom), using the supplied format string.

Reference for the custom format syntax: SciX Help: Export Results.

Important details from the SciX custom-format reference:

• Syntax is printf-like with % conversion specifiers.

• Author truncation can use %[n.m]l (example: %3.2l).

• Useful author directives include %l, %A, %G, %m, %M.

• In adsfolio cv, this custom output replaces only the author segment of each rendered entry.

• Custom author formatting makes an export request per publication. If that request raises ADSError, generation logs a warning and retains local author formatting for that publication.

Journal handling

• journal display uses format_journal(..., fmt="full")

• adsfolio cv normalizes arXiv e-prints to arXiv

• adsfolio cv can append an optional bibstem-to-journal legend

Full example

See the tutorial page for a full working YAML and end-to-end command sequence:

• Tutorial 6: CV Workflows