Citation System

A hex-code based citation system that converts to sequential integers at render time. Components for inline citations, source lists, and wrapper utilities.

Architecture

The citation system uses hex codes (e.g., alyqs4) as stable identifiers that get converted to sequential integers ([1], [2], [3]) at render time based on order of appearance.

Key Types

  • CitationReference - Source definition with hexCode, title, url
  • IndexedCitation - Citation with assigned index number

Utilities

  • buildCitationIndex() - Assigns sequential indices
  • citationsToArray() - Converts map to sorted array

InlineCitation

Renders an inline citation marker [n] with a hover popover showing source details. Uses a global popover pattern for reliable cross-browser behavior.

Live Example

Healthcare costs are projected to rise 7-8% annually for US employers [1] , driven primarily by chronic conditions which account for 90% of US healthcare spend [2] . Cancer has become the leading condition driving insurer costs globally [3] .

Props

Prop Type Description
index number Sequential index for display (1, 2, 3...)
hexCode string Hex code identifier for the citation
title string Title of the source
url string URL to the source
source? string Publication name or domain
publishedDate? string Published date for display

Usage

const cite = citationIndex.get('alyqs4');
<p>Some text<InlineCitation {...cite} /></p>

Sources

Full sources section with titles, metadata, and external links. Best for end-of-section or end-of-page source listings.

Live Example

Sources

  1. [1]
    Key Drivers of 2025 Health Care Cost Increases
    Parrott Benefit Group•2024-11-22
  2. [2]
    Why Health Care Costs Are Rising in 2025
    Watkins Insurance Group•2025-01-30
  3. [3]
    Global Healthcare Costs Projected to Rise More Than 10% in 2026
    WorldatWork•2025-11-13
  4. [4]
    How heavy is the medical expense burden among the older adults
    NIH/PMC•2023-06-16
  5. [5]
    Fidelity Investments Releases 2025 Retiree Health Care Cost Estimate
    Fidelity Investments•2025-07-30

Props

Prop Type Default Description
citations IndexedCitation[] - Array of indexed citations to display
title? string "Sources" Section title

Usage

<Sources
  citations={citationsToArray(citationIndex)}
  title="References"
/>

SourcesCompact

Compact variant for tight spaces like cards, sidebars, or inline sections. Shows source names in an inline flex layout with smaller typography.

Live Example

Sources

  1. [1]Parrott Benefit Group
  2. [2]Watkins Insurance Group
  3. [3]WorldatWork
  4. [4]NIH/PMC
  5. [5]Fidelity Investments

Without Title

  1. [1]Parrott Benefit Group
  2. [2]Watkins Insurance Group
  3. [3]WorldatWork
  4. [4]NIH/PMC
  5. [5]Fidelity Investments

Props

Prop Type Default Description
citations IndexedCitation[] - Array of indexed citations
title? string "Sources" Section title
hideTitle? boolean false Hide the title
class? string "" Additional CSS classes

Usage

<SourcesCompact
  citations={citationsArray}
  title="Sources"
  hideTitle={false}
/>

SourcesInline

Minimal inline variant for tight spaces. Renders as a single line with clickable [n] indices. Best for captions, cards, or subtle source attribution.

Live Example

Healthcare costs are rising due to aging demographics and chronic disease burden.

Sources: [1] , [2] , [3] , [4] , [5]

Custom Prefix

References: [1] , [2] , [3]

Props

Prop Type Default Description
citations IndexedCitation[] - Array of indexed citations
prefix? string "Sources:" Prefix text
showTitles? boolean true Show full titles on hover
class? string "" Additional CSS classes

Usage

<SourcesInline
  citations={citationsArray}
  prefix="Refs:"
  showTitles={true}
/>

CitedSection

Wrapper component that handles citation indexing and renders the appropriate Sources variant. Simplifies the pattern of content + sources by handling the boilerplate.

Live Example (Compact Variant)

This is content inside a CitedSection. The sources are automatically rendered at the end based on the sourcesVariant prop.

Sources

  1. [1]Parrott Benefit Group
  2. [2]Watkins Insurance Group
  3. [3]WorldatWork

Inline Variant

A brief stat card with minimal source attribution.

Sources: [1] , [2] , [3]

Props

Prop Type Default Description
citations CitationReference[] - Array of citation references
sourcesVariant? 'full' | 'compact' | 'inline' | 'none' 'full' Which Sources variant to render
sourcesTitle? string 'Sources' Title for the Sources section
class? string "" Additional CSS classes
as? 'section' | 'div' | 'article' 'section' Element tag for the wrapper

Usage

<CitedSection
  citations={citationRefs}
  sourcesVariant="compact"
  sourcesTitle="References"
>
  <p>Content with citations goes here...</p>
</CitedSection>

Variant Comparison

Side-by-side comparison of all three Sources variants with the same citation data.

Full (default)

Best for: End of sections, detailed references

Sources

  1. [1]
    Key Drivers of 2025 Health Care Cost Increases
    Parrott Benefit Group•2024-11-22
  2. [2]
    Why Health Care Costs Are Rising in 2025
    Watkins Insurance Group•2025-01-30
  3. [3]
    Global Healthcare Costs Projected to Rise More Than 10% in 2026
    WorldatWork•2025-11-13

Compact

Best for: Cards, sidebars, tight layouts

Sources

  1. [1]Parrott Benefit Group
  2. [2]Watkins Insurance Group
  3. [3]WorldatWork

Inline

Best for: Captions, footnotes, minimal attribution

Sources: [1] , [2] , [3]

File Locations

src/components/citations/InlineCitation.astro Inline [n] marker with popover
src/components/citations/Sources.astro Full sources section
src/components/citations/SourcesCompact.astro Compact sources variant
src/components/citations/SourcesInline.astro Inline sources variant
src/components/citations/CitedSection.astro Wrapper component
src/lib/citations/types.ts Types and utility functions