units-quarto-extension/README.md

units: A Quarto Extension for Standardized Scientific Unit Notation

This extension provides a centralized, extensible mechanism for the consistent rendering of physical quantities across Quarto-based scientific websites and publications. It is designed principally for use in computational chemistry, biochemistry, and computer-aided drug design (CADD), disciplines in which a single document routinely reports energies, distances, timescales, concentrations, electrostatic potentials, and temperatures spanning many orders of magnitude and multiple unit systems.

Motivation

The correct typographic and semantic treatment of physical quantities is governed by well-established conventions. Most notably those of the International Bureau of Weights and Measures (BIPM) as codified in the SI Brochure, and their discipline-specific elaborations in the IUPAC Quantities, Units and Symbols in Physical Chemistry ("Green Book") and NIST Special Publication 811. These conventions specify, among other things: upright (non-italic) typesetting of unit symbols; a non-breaking space between a numerical value and its associated unit; the use of negative exponents rather than stacked solidi for compound units; and unambiguous conversion factors between coherent and non-coherent units within a given physical dimension.

In practice, manuscripts and websites authored under time constraints tend to depart from these conventions inconsistently: for example, a bond length may be rendered as 1.54 Å in one section and 1.54Å (with an ordinary, breakable space) in another or an energy value may be transcribed from kJ·mol⁻¹ to kcal·mol⁻¹ by hand.

Installation

You can install this Quarto extension with the following command:

quarto add https://git.scient.ing/infra/units-quarto-extension/archive/main.zip

Following installation, confirm the presence of the extension within the project:

_extensions/
└── units/
    ├── _extension.yml
    └── units.lua

A minimal document using the extension should render without error:

---
title: "Installation Check"
---

The bond length is {{< distance 1.54 angstrom >}}.

Reference: Shortcodes

Shortcode	Signature	Description
unit	{{< unit <unit-key> >}}	Renders the typeset symbol for a single unit, with no numerical value or conversion.
sci	{{< sci <value> >}}	Renders a bare numerical value in scientific notation, independent of any unit.
energy	{{< energy <value> <unit> [<target-unit>] >}}	Bulk (non-molar) energy: J, kJ, cal, kcal.
molarenergy	{{< molarenergy <value> <unit> [<target-unit>] >}}	Molar energy: J/mol, kJ/mol, cal/mol, kcal/mol, eV, hartree, cm⁻¹.
distance	{{< distance <value> <unit> [<target-unit>] >}}	Distance: angstrom, nanometer, picometer, bohr, meter.
time	{{< time <value> <unit> [<target-unit>] >}}	Time: second and its SI-prefixed subdivisions, plus minute, hour, day.
concentration	{{< concentration <value> <unit> [<target-unit>] >}}	Molar concentration: M, mM, μM, nM, pM, fM.
voltage	{{< voltage <value> <unit> [<target-unit>] >}}	Electrical potential: kV, V, mV, μV.
temperature	{{< temperature <value> <unit> [<target-unit>] >}}	Temperature: kelvin, celsius, fahrenheit (affine conversion).
massconc	{{< massconc <value> <mass-unit> <molar-mass> <target-unit> >}}	Mass-per-volume concentration converted to molar concentration given an explicit molar mass.

Each quantity shortcode accepts an optional keyword argument, notation=sci or notation=plain, which overrides the automatic determination of numerical formatting described in Section 6.

Supported Unit Categories

Bulk Energy (base unit: joule)

Unit key	Symbol	Notes
J	J	SI base representation
kJ	kJ
cal	cal	Thermochemical calorie (1 cal = 4.184 J)
kcal	kcal

Molar Energy (base unit: kJ·mol⁻¹)

Unit key	Symbol	Notes
J/mol	J·mol⁻¹
kJ/mol	kJ·mol⁻¹
cal/mol	cal·mol⁻¹
kcal/mol	kcal·mol⁻¹
eV	eV	1 eV = 96.485 kJ·mol⁻¹
hartree	Eₕ	Atomic unit of energy; 1 hartree = 2625.5 kJ·mol⁻¹
cm-1	cm⁻¹	Wavenumber, as conventionally reported in vibrational spectroscopy

Distance (base unit: ångström)

Unit key	Symbol	Notes
angstrom	Å	Rendered using U+00C5, the canonical (NFKC-normalized) form
nanometer	nm
picometer	pm
bohr	a₀	Atomic unit of length
meter	m

Time (base unit: second)

Unit key	Symbol
second	s
millisecond	ms
microsecond	μs
nanosecond	ns
picosecond	ps
femtosecond	fs
minute	min
hour	h
day	d

Molar Concentration (base unit: molar)

Unit key	Symbol
molar	M
millimolar	mM
micromolar	μM
nanomolar	nM
picomolar	pM
femtomolar	fM

Mass Concentration (base unit: mg·mL⁻¹)

Unit key	Symbol
mg/mL	mg·mL⁻¹
μg/mL	μg·mL⁻¹
ng/mL	ng·mL⁻¹

This category is consumed exclusively by the massconc shortcode, which additionally requires a molar mass argument to compute the corresponding molar concentration.

Voltage (base unit: volt)

Unit key	Symbol
kilovolt	kV
volt	V
millivolt	mV
microvolt	μV

Temperature

Unit key	Symbol	Conversion basis
kelvin	K	Identity (SI base unit; no degree sign, per convention)
celsius	°C	T(K) = T(°C) + 273.15
fahrenheit	°F	T(K) = [T(°F) + 459.67] × 5/9

Numerical Formatting

The rendered representation of a numerical value is determined automatically unless overridden by the notation keyword argument.

By default, a value is formatted to three significant figures using fixed decimal notation. Should this formatting internally require exponential notation, the extension instead renders the value in explicit scientific notation, with the mantissa and a true superscript exponent joined by a non-breaking multiplication sign:

{{< sci 6.02214076e23 >}}

renders as 6.022 × 10²³, rather than the unprocessed string 6.02e+23.

Worked Examples

Distance

The O–H bond length is {{< distance 0.96 angstrom >}}.
Converted to nanometers: {{< distance 1.54 angstrom nanometer >}}.

The O–H bond length is 0.96 Å. Converted to nanometers: 1.54 Å (0.154 nm).

Bulk Energy

Combustion releases {{< energy 4.18 J >}} of heat under these conditions.

Combustion releases 4.18 J of heat under these conditions.

Molar Energy

The activation barrier was {{< molarenergy 45.2 kJ/mol kcal/mol >}}.
A single-point DFT energy of {{< molarenergy 0.0421 hartree kcal/mol >}} was obtained.

The activation barrier was 45.2 kJ·mol⁻¹ (10.8 kcal·mol⁻¹). A single-point DFT energy of 0.0421 Eₕ (110 kcal·mol⁻¹) was obtained.

Time

The production molecular dynamics simulation was extended to
{{< time 500 nanosecond microsecond >}}, using an integration timestep of
{{< time 2e-15 second femtosecond >}}.

The production molecular dynamics simulation was extended to 500 ns (0.5 μs), using an integration timestep of 2 × 10⁻¹⁵ s (2 fs).

Molar Concentration

The compound exhibited a Kᵢ of {{< concentration 12 nanomolar >}}
against the target enzyme.

The compound exhibited a Kᵢ of 12 nM against the target enzyme.

Voltage

Resting membrane potential was recorded at {{< voltage -70 millivolt >}}.

Resting membrane potential was recorded at -70 mV.

Temperature

Assays were conducted at {{< temperature 25 celsius kelvin >}}, approximating
physiological temperature of {{< temperature 310.15 kelvin celsius >}}.

Assays were conducted at 25 °C (298 K), approximating physiological temperature of 310.15 K (37 °C).

Scientific Notation and Rate Constants

The observed second-order rate constant was
{{< concentration 2.1e6 molar notation=sci >}}⁻¹·{{< unit second >}}⁻¹.

The observed second-order rate constant was 2.1 × 10⁶ M⁻¹·s⁻¹.

Mass-to-Molar Concentration Conversion

A stock solution prepared at {{< massconc 0.5 mg/mL 350.4 micromolar >}}
was used for the binding assay.

A stock solution prepared at 0.5 mg·mL⁻¹ (1.43 μM, MW 350.4 g/mol) was used for the binding assay.