Style Author Guide

compare_arrows How Citum Differs from CSL 1.0

Citum introduces a modern, declarative approach to citation styling compared to CSL 1.0's procedural XML language. Understanding these differences is essential for writing Citum styles effectively.

Aspect	CSL 1.0 (XML)	Citum (YAML)
Format	Procedural XML markup	Declarative YAML
Logic	choose/if/else conditionals	Type overrides + inheritance
Name Formatting	Inline XML attributes	Global presets + options
Dates	Object with year/month/day	EDTF string format
Inheritance	Parent style aliasing	Presets + type overrides
Readability	Verbose and nested	Concise and explicit

lightbulb

Explicit Over Magic

Citum styles are explicitly declarative. Special behavior is expressed in the style itself, not hidden in processor logic. If you need different punctuation for journals vs books, you declare it with type overrides. This makes styles portable, testable, and understandable without reading source code.

folder_special Style File Anatomy

Every Citum style file contains four top-level sections: metadata, options, citation template, and bibliography template.

Minimal Style Skeleton

# yaml-language-server: $schema=https://citum.github.io/citum-core/schemas/style.json

info:
  title: "My Style Name"
  id: "my-style"
  link: "https://example.com/style"
  default-locale: "en-US"

options:
  mode: author-date

citation:
  template:
    - contributor: author
    - date: issued

bibliography:
  template:
    - contributor: author
    - date: issued
    - title: primary

tips_and_updates

Editor autocomplete and validation

The yaml-language-server comment in the skeleton above enables full autocomplete and inline validation in editors that support the YAML Language Server protocol. Supported editors include VS Code with the Red Hat YAML extension, Helix, and Zed.

Add this as the first line of any Citum style file:

# yaml-language-server: $schema=https://citum.github.io/citum-core/schemas/style.json

See Schema & Editor Integration on the home page for the full schema list and setup instructions.

Info Fields

title

Human-readable name of your style (e.g., "American Psychological Association 7th Edition").

id

Unique identifier in kebab-case (e.g., "apa-7th"). Used for style selection.

link

URL to the style documentation or official specification.

default-locale

BCP 47 language tag for locale-specific terms, months, and contributor roles (e.g., "en-US", "de-DE").

tune Global Options

Global options control the processing mode and apply defaults to all components in both citation and bibliography templates.

Processing Modes

Mode	Description	Example Citation
author-date	Author-date system with author and year	(Smith, 2020)
numeric	Numbered citations with numeric keys	[1]
note	Footnote-based citations	Smith, "Title," 2020

Contributor Presets

Named presets control name formatting without spelling out every field:

apa

Family-first, "&" symbol, initials with period-space, et al. after 20. Example: "Smith, J. D., & Jones, M. K."

chicago

Family-first, "and" text, full given names, contextual serial comma. Example: "Smith, John D., and Mary K. Jones"

vancouver

All family-first, no conjunction, compact initials (no periods), et al. after 6 of 7+. Example: "Smith JD, Jones MK"

ieee

Given-first, "and" text, initials with period-space. Example: "J. D. Smith, M. K. Jones, and A. B. Brown"

harvard

All family-first, "and" text, compact initials (period, no space). Example: "Smith, J.D., Jones, M.K., and Brown, A.B."

springer

All family-first, no conjunction, compact initials, et al. after 3 of 5+. Example: "Smith JD, Jones MK, Brown AB"

numeric-compact

All family-first, no conjunction, sort-only particle demotion, et al. after 6 of 7+.

numeric-medium

Same as numeric-compact, but et al. after 3 of 4+.

Date Presets

Preset	Format	Example
long	Full month names, EDTF markers, en-dash ranges	January 15, 2024
short	Abbreviated month names	Jan 15, 2024
numeric	Numeric months	1/15/2024
iso	ISO 8601, no EDTF markers	2024-01-15

Title Presets

Title presets control how article, book, and journal titles are formatted (italic, quoted, or plain):

Preset	Articles	Books & Journals
apa	Plain	Italic
chicago	Quoted	Italic
ieee	Quoted	Italic
humanities	Plain	Italic (incl. series)
journal-emphasis	Plain	Journal + serial italic, monograph plain
scientific	Plain	Plain

Substitute Presets

Substitute presets define the fallback order when the primary author is missing:

Preset	Fallback order
standard	Editor → Title → Translator (APA, Chicago, etc.)
editor-first	Editor → Translator → Title
title-first	Title → Editor → Translator (anonymous works)
editor-short	Editor only (short role form)
editor-long	Editor only (long role form)
editor-translator-short	Editor → Translator (short role form)
editor-translator-long	Editor → Translator (long role form)
editor-title-short	Editor → Title (short role form)
editor-title-long	Editor → Title (long role form)
editor-translator-title-short	Editor → Translator → Title (short role form)
editor-translator-title-long	Editor → Translator → Title (long role form)

Template Preset

Use citation.use-preset: numeric-citation when the citation template is only a citation number and wrapping is controlled by style options.

citation:
  use-preset: numeric-citation
  wrap: brackets

Other Options

page-range-format

How to compress page ranges: expanded (123–145), minimal (123–45), minimal-two (keeps two digits minimum), chicago, chicago16

bibliography.hanging-indent

Whether bibliography entries use hanging indent formatting

bibliography.separator

Separator between bibliography entries (semicolon, period, etc.)

layers Template Components

Templates are arrays of components that describe how to render citations and bibliographies. Each component type handles a specific data element.

Contributor

Renders author, editor, translator, and other contributors.

- contributor: author
  form: long          # long | short | verb | verb-short
  name-order: family-first  # family-first | given-first
  label:
    term: editor
    form: short

role

author, editor, translator, director, publisher, recipient, interviewer, inventor, etc.

form

long (full names), short (last names only), verb (substitute, editor becomes "edited by"), verb-short

name-order

family-first for "Smith, John" or given-first for "John Smith"

Date

Renders date fields using EDTF format with locale-specific formatting.

- date: issued
  form: year  # year | year-month | full | month-day | year-month-day

variable

issued, accessed, original-published, submitted, event-date

form

year (2020), year-month (2020 March), full (March 15, 2020), month-day (March 15), year-month-day (2020 March 15)

Title

Renders the title of the item with optional parent-level titles.

- title: primary
  form: long  # long | short

type

primary (the item's title), parent-monograph (book title), parent-serial (journal name)

Number

Renders numeric data: volume, issue, pages, edition, etc.

- number: pages
  form: numeric  # numeric | ordinal | roman

variable

volume, issue, pages, edition, citation-number, collection-number, number

form

numeric (1, 2, 3), ordinal (1st, 2nd, 3rd), roman (I, II, III)

Variable

Renders any other metadata variable as plain text.

- variable: publisher
  prefix: ""

variable

publisher, publisher-place, doi, url, genre, medium, note, authority, reporter, locator, and many others

Term

Outputs locale-specific text like "Editor" or "Eds."

- term: editor
  form: short  # long | short | symbol

List

Groups multiple components with a delimiter between them.

- items:
    - contributor: author
    - date: issued
  delimiter: ", "

formatting Rendering Options

Every component can be modified with rendering options that control punctuation, formatting, and text wrapping.

Positioning: How Prefix/Suffix and Wrapping Work Together

prefix + (inner-prefix + value + inner-suffix) + suffix

Example: if prefix is "(", inner-prefix is "[", value is "Smith", inner-suffix is "]", and suffix is ")", the result is "([Smith])".

Option	Values	Purpose
prefix	" ", "(", "["	Text before the component
suffix	", ", ".", ")"	Text after the component
wrap	parentheses, brackets, quotes, none	Automatically wrap value with punctuation
emph	true, false	Render in italics
strong	true, false	Render in bold
small-caps	true, false	Render in small capitals
suppress	true, false	Hide the component
strip-periods	true, false	Remove periods from abbreviations

settings_input_component Type Overrides

Instead of using procedural conditionals, Citum components declare type-specific overrides that modify their behavior for specific reference types.

Pattern 1: Suppress for a Type

Hide the publisher for journal articles (they don't typically show the publisher):

- variable: publisher
  overrides:
    article-journal: { suppress: true }

Pattern 2: Change Rendering for a Type

Add "pp. " prefix to page numbers only for chapters:

- number: pages
  overrides:
    chapter:
      prefix: "pp. "

Pattern 3: Apply Rule to Multiple Types

Use a list to apply the same override to multiple types:

- variable: publisher
  overrides:
    [article-journal, webpage, broadcast]:
      suppress: true

Pattern 4: Use "all" for Default, Override for Exceptions

Set a default and override specific types:

- title: primary
  emph: true         # Default: italicize
  overrides:
    article-journal: { emph: false }  # Exception: don't italicize

category Type Templates

For reference types that need completely different component layouts, use type-specific templates. This is more flexible than per-component overrides.

bibliography:
  template:
    - contributor: author
    - date: issued
    - title: primary

  type-templates:
    article-journal:     # Single type
      - contributor: author
      - date: issued
      - title: primary
      - title: parent-serial

    [book, report]:        # Multiple types with same template
      - contributor: author
      - variable: publisher
      - date: issued

    []                        # Empty list: suppress this type entirely

info

Type-Templates Override Default Template

If a reference type has an entry in type-templates, that template is used instead of the default template. Use an empty list [] to suppress specific types entirely.

share Options Inheritance

Global options apply to all components, but can be overridden at the citation and bibliography level, allowing fine-grained control.

options:
  contributors: apa       # Global: family-first, initials, up to 20 names

citation:
  options:
    contributors:
      et-al-min: 3        # Citation-level: only show 3 names before et al
      et-al-use-first: 1
  template: [...]

bibliography:
  options:
    contributors:
      et-al-min: 20       # Bibliography-level: show all up to 20
  template: [...]

Inheritance Chain

1. Component-level options (highest priority)
2. Citation/Bibliography-level options
3. Global options (lowest priority)

list Reference Types

Citum supports all standard CSL 1.0 reference types plus extensions for legal and specialized content.

article

article-journal

article-magazine

article-newspaper

book

broadcast

chapter

dataset

document

entry-dictionary

entry-encyclopedia

interview

map

motion-picture

musical-score

pamphlet

paper-conference

personal-communication

report

speech

thesis

webpage

code Complete Examples

Here are two minimal but complete working styles demonstrating author-date and numeric modes.

Example 1: Minimal Author-Date Style

A basic APA-like style with author, year, and title.

info:
  title: "Simple Author-Date"
  id: "simple-author-date"
  default-locale: "en-US"

options:
  mode: author-date
  contributors: apa

citation:
  template:
    - contributor: author
    - date: issued
      prefix: " "
      wrap: parentheses

bibliography:
  template:
    - contributor: author
    - date: issued
      prefix: " "
    - title: primary
      prefix: " "
      suffix: "."
    - variable: publisher
      prefix: " "
      suffix: "."
      overrides:
        article-journal: { suppress: true }

Example 2: Minimal Numeric Style

A basic IEEE-like numeric style with numbered citations.

info:
  title: "Simple Numeric"
  id: "simple-numeric"
  default-locale: "en-US"

options:
  mode: numeric

citation:
  template:
    - number: citation-number
      wrap: brackets

bibliography:
  template:
    - number: citation-number
      suffix: ". "
    - contributor: author
    - date: issued
      prefix: " "
    - title: primary
      prefix: " "
    - title: parent-serial
      prefix: " in "
      emph: true

lightbulb Workflow & Common Mistakes

Recommended Workflow

1

Start with a reference style
Use an existing CSL 1.0 or Citum style as a template
2

Write metadata in info block
Set title, id, link, and default locale
3

Define global options
Set mode and contributor/date presets
4

Write citation template
Start with author, date, maybe title
5

Test with oracle
Compare output against citeproc-js reference implementation
6

Iterate with type overrides
Add overrides for specific types to match expected output

Common Mistakes to Avoid

warning

Forgetting type overrides

Different reference types need different layouts (journals vs books). Use type-templates or overrides to handle these.

warning

Over-complicated options inheritance

Keep global options simple. Override only at citation/bibliography level when truly needed.

warning

Mismatching prefix/suffix pairs

Always pair opening prefix with closing suffix. Don't leave mismatched parentheses.

warning

Suppressing components instead of overriding

If a component needs different rendering for a type, override its properties. Only suppress if it shouldn't appear at all.

Verification Commands

Use these commands to test your style:

$ cargo run --bin citum -- render refs \
  -b tests/fixtures/references-expanded.json \
  -s styles/my-style.yaml

Render citations and bibliography with your style

$ node scripts/oracle.js styles/my-style.yaml

Compare output against citeproc-js reference