# rehype-chemfig
**Chemfig drawing syntax → accessible SVG in Markdown and HTML. No TeX installation.**
A TypeScript renderer for a **documented subset** of [Chemfig](https://ctan.org/pkg/chemfig), with plugins for [rehype](https://github.com/rehypejs/rehype) and [remark](https://github.com/remarkjs/remark). Write a molecule in a code fence; get a crisp, selectable SVG figure in your document.
[Quick start](#quick-start) · [Examples](#examples) · [Options](#options) · [Supported syntax](#supported-syntax) · [Development](#development)
- **Local and synchronous.** No TeX, remote rendering service, CDN, or browser needed to generate SVG.
- **Real document nodes.** Emits HAST SVG elements, not injected raw HTML. No `allowDangerousHtml` required.
- **Block and inline.** Fenced figures, inline structures, optional remark captions, and accessible SVG titles.
- **Style with CSS.** Bonds and labels inherit `currentColor`; the optional stylesheet handles sizing and alignment.
- **Use only what you need.** ESM, TypeScript declarations, standalone rendering APIs, and browser-compatible core.
> This is an independent implementation of a Chemfig **subset**, not a TeX engine or a chemical toolkit. It does not validate valence, infer hydrogens, interpret SMILES, or promise pixel-identical TeX output. [Check the boundaries before adopting it.](#unsupported-and-intentionally-stricter-cases)
## Installation
The intended package name is **`rehype-chemfig`**, following the unified ecosystem's `rehype-*` convention. It includes the remark plugin too. This repository is not published to npm yet. Once published:
```sh
bun add rehype-chemfig unified remark-parse remark-rehype rehype-stringify
```
For local use now, run `bun install` and `bun pm pack` in this repository, then `bun add /path/to/rehype-chemfig-0.1.0.tgz` in your application. Packing builds the package automatically. Consumers can use any package manager; **Bun is used to develop this repository**, not required by the published renderer. Node.js 20+ and modern browsers are supported.
## Quick start
````js
import { unified } from 'unified';
import remarkParse from 'remark-parse';
import remarkRehype from 'remark-rehype';
import rehypeStringify from 'rehype-stringify';
import rehypeChemfig from 'rehype-chemfig';
const markdown = '```chemfig\n*6(-=-=-=)\n```';
const file = await unified()
.use(remarkParse)
.use(remarkRehype)
.use(rehypeChemfig)
.use(rehypeStringify)
.process(markdown);
console.log(String(file)); //
````
Add `import 'rehype-chemfig/styles.css'` to your application's stylesheet entry if your bundler supports CSS imports. No browser JavaScript is needed to display the generated figures.
## Examples
All images below are generated by this project's renderer. Click a structure to open its standalone SVG.
| Aromatic ring | Stereochemistry | Charged group |
| :-------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------: |
| [](assets/examples/phenol.svg) | [](assets/examples/lactic-acid.svg) | [](assets/examples/acetate.svg) |
| **Phenol** · aromatic circle | **Lactic acid** · solid / hashed wedges | **Acetate** · subscripts / superscripts |
**[Browse all 10 examples with copyable Markdown](docs/examples.md)**, including aspirin, caffeine, benzene, ethanol, glycine, acetonitrile, and pyridine.
Try the editable drawing bench locally:
```sh
bun install
bun run dev --host # http://localhost:4173; override with PORT=…
```
Choose an example, edit its source, and download the result as standalone SVG. Initial figures are built with the remark plugin; edits run the same pipeline in the browser, entirely locally.
## Markdown syntax
Use a `chemfig` fence. The content is either the molecule body or a single `\chemfig{…}` wrapper. An optional **plain-text fence meta string** becomes a visible caption and accessible name:
````md
```chemfig Acetate
H_3C-C(=[:90]O)-O^{-}
```
An alcohol group, `chemfig: H_3C-CH_2-OH`, within a paragraph.
```chemfig Benzene
\chemfig{*6(-=-=-=)}
```
````
Inline syntax is deliberately an **inline code span starting with `chemfig:`**. This preserves backslashes, braces, `<`, `>`, `*`, and `_` before Markdown can interpret them. Bare `\chemfig{…}` in prose and math delimiters are **not** recognized. Ordinary code remains ordinary code. Set `inline: false` to disable inline rendering.
## With rehype / HTML
The default export is `rehypeChemfig`. As shown in the [quick start](#quick-start), place it **after `remarkRehype` and before syntax highlighting**. Already-highlighted code with element children is deliberately left untouched.
It also works on existing HTML with `rehype-parse`:
```js
import { unified } from 'unified';
import rehypeParse from 'rehype-parse';
import rehypeStringify from 'rehype-stringify';
import rehypeChemfig from 'rehype-chemfig';
const file = await unified()
.use(rehypeParse, { fragment: true })
.use(rehypeChemfig)
.use(rehypeStringify)
.process('
*6(-=-=-=)
');
```
In HTML source, use `<` for `<` wedge tokens. The plugin reads decoded text nodes. It only replaces `
` containing one `language-chemfig` code element, and explicitly marked inline code; unrelated code is not interpreted.
## With remark and captions
Use the remark plugin **before `remarkRehype`** when you want fence captions preserved:
````js
import { unified } from 'unified';
import remarkParse from 'remark-parse';
import remarkRehype from 'remark-rehype';
import rehypeStringify from 'rehype-stringify';
import { remarkChemfig } from 'rehype-chemfig';
const markdown = '```chemfig Benzene\n*6(-=-=-=)\n```';
const file = await unified()
.use(remarkParse)
.use(remarkChemfig, { errorMode: 'throw' })
.use(remarkRehype)
.use(rehypeStringify)
.process(markdown);
console.log(String(file));
````
The remark plugin replaces matching code nodes with custom `chemfig` mdast nodes carrying standard `data.hName`, `data.hProperties`, and `data.hChildren`. `remark-rehype` handles them without custom handlers or `allowDangerousHtml`. Block figures become `` and inline drawings become ``, each containing a real `