Chemistry in Metanorma

The citation loop closes inside Metanorma documents: with the metanorma-plugin-asciichem gem, chemistry written in AsciiChem renders as formulas, and @cite-annotated molecules resolve into dataset-type bibliography entries — one per (source, substance), anchored by InChIKey — collected into the document’s References section without any manual bibliography work.

Installation

gem install metanorma-plugin-asciichem

Like the other plugins in the family (lutaml, glossarist), the gem is wired through metanorma-standoc: once installed, [chem] and chem:[] are active in every Metanorma compile, in any flavour — no per-document setup.

Chemistry blocks

[chem]
----
2H_2 + O_2 -> 2H_2O
----

The block parses into AsciiChem’s semantic model and renders as MathML — in the semantic XML, <formula><stem type="MathML">, the same shape Metanorma uses for mathematics, so every flavour renders it. Block ids and titles carry over ([chem#reaction,title="Hydrolysis"]).

Inline chemistry works too:

Water is chem:H_2O[] in prose — or chem:[2H_2 + O_2 -> 2H_2O]
when the source contains spaces.

Inline macros render; they do not collect citations (inline substitution runs after the document pass that gathers them).

Invalid AsciiChem logs an error and keeps the original block as sourcecode — the build stays reproducible and the problem stays visible.

Substances cite themselves

The cite syntax rides along: annotate the molecule in a [chem] block and the build resolves it and appends the bibliography.

[chem]
----
CC(=O)OC1=CC=CC=C1C(=O)O @cas("50-78-2") @cite("pubchem")
----

The substance record is <<BSYNRYMUTXBXSQ-UHFFFAOYSA-N>>.

A [bibliography] section appears at the end of the document with one <bibitem type="dataset"> per (source, substance):

• the same substance cited twice yields one deduplicated entry per source;
• two sources yield two entries — PubChem and CAS Common Chemistry are different documents — both anchored by the same InChIKey, the cross-document join key;
• every identifier the source returned rides along as a keyword, so citations stay machine-checkable.

Resolution uses the same code path as asciichem cite, so a document and the command line can never disagree.

Offline, reproducible builds

Resolution reads the AsciiChem resolver cache. Point the document at a seeded cache to build with no network:

:asciichem-cache-dir: ./.asciichem-cache

Seed it with asciichem resolve --name aspirin. Failures warn and emit no bibitem; they never break the build.

Which sources can be cited — and the licence story (PubChem by default, CAS Common Chemistry opt-in under CC BY-NC) — is the same as on the citing substances page.

A complete worked example ships with the gem: docs/example.adoc.