Skip to content

Chemistry Diagram Rendering Options

Prompt

I want to create a new course on Chemistry using the mkdocs documentation system. I want to be able to describe a chemical diagram in a declarative way and have it render professionally. What are my options?

ChatGPT Said (GPT-5.2 Thinking)

If your goal is “write chemistry diagrams declaratively in Markdown and have MkDocs render them professionally,” you’ve basically got 4 strong paths (and they can mix well in one course).

1) Chemical formulae & reactions in Markdown via LaTeX-style math + mhchem

Best for: formulas, ions, equilibria, reaction equations, states, stoichiometry (not structural line drawings).

  • MkDocs Material supports math rendering via MathJax or KaTeX. (squidfunk.github.io)
  • The mhchem syntax is commonly used with MathJax/KaTeX setups to typeset chemical equations cleanly (e.g., \ce{2H2 + O2 -> 2H2O}). (overleaf.com)
  • This gives you the “professional textbook look” for equations with minimal friction.

Where it stops: mhchem is for equations/formulae, not molecular structure diagrams. (TeX - LaTeX Stack Exchange)

2) Structural diagrams (rings/bonds) with LaTeX chemfig or TikZ, rendered to SVG at build time

Best for: “publication-quality” structure drawings where typography and layout consistency matter a lot.

  • chemfig is a classic LaTeX package for drawing structural formulae. (overleaf.com)
  • In a MkDocs workflow, you typically render these to SVG/PNG during the build, then embed the image in the page. (There are MkDocs-adjacent approaches that render TikZ/diagrams to files as part of the build pipeline.) (GitHub)

Pros:

  • Highest “typeset” quality.
  • Fully declarative and version-controllable in your repo.

Cons:

  • Requires a LaTeX toolchain in CI (or Docker) and a diagram-to-image step.

3) Declarative molecule drawing from SMILES (fastest “write text → get structure” loop)

Best for: lots of molecules, organic structures, consistent 2D drawings generated from a canonical text representation.

Two popular browser-rendering options:

  • SmilesDrawer: parses & draws SMILES to SVG in the browser (MIT-licensed, widely used). (GitHub)
  • Kekule.js: broader cheminformatics toolkit (reads/writes formats like SMILES, CML, MOL; provides rendering and widgets). (Partridge Jiang)

How it usually looks in MkDocs:

  • You write something like a fenced block containing SMILES (or an inline tag).
  • A small JS snippet (or a Markdown-it style plugin equivalent) converts that text into an SVG diagram at page load. There are existing SMILES-to-render helpers in the ecosystem built around SmilesDrawer. (GitHub)

Pros:

  • Extremely scalable for a whole course: you can store molecules as SMILES in Markdown, YAML, or JSON and render everywhere.
  • Great for “data-first” content and reuse (quizzes, flashcards, glossaries, etc.).

Cons:

  • It’s “web-rendered,” so PDF export workflows can require extra care if you later want print-ready output.

4) Build-time rendering to SVG/PNG from SMILES/MOL (best for PDFs + consistent output)

Best for: you want the declarative convenience of SMILES and you want deterministic, printable assets.

Typical approach:

  • Author molecules as SMILES (or molfile/CML).
  • Use a build step (often Python-based) to convert each molecule into SVG/PNG during mkdocs build.
  • Embed the generated images.

This is a very “MkDocs-native” pattern because MkDocs is already a build pipeline. It also gives you:

  • Stable diagrams across browsers
  • Easy PDF generation later
  • No client-side rendering dependency

(Under the hood people often use chemistry toolkits like RDKit/Open Babel for this, but the key point is the workflow pattern.)

Bonus: 3D structures / crystal / protein viewers (interactive)

If you expect to teach geometry, orbitals, conformers, or bio-related chemistry, consider embedding a 3D web viewer (often fed by PDB/SDF/MOL2). This complements (not replaces) the 2D diagram options above.

A pragmatic “Chemistry course” stack that works well in MkDocs

If you want a clean, low-maintenance setup:

  • Equations/reactions: MathJax/KaTeX + mhchem (squidfunk.github.io)

  • Molecules in bulk: SMILES → (a) SmilesDrawer in-browser (GitHub)

  • or (b) build-time SMILES → SVG if you care about PDF/print consistency

  • Occasional “journal-quality” drawings: chemfig/TikZ rendered to SVG at build time (overleaf.com)

That mix gives you: fast authoring, professional output, and an escape hatch for the hard diagrams.

If you tell me what kinds of diagrams you mean (Lewis structures? orgo line-angle? reaction mechanisms with curved arrows? lab apparatus? orbital/energy diagrams?), I can recommend a tighter “one primary representation” choice and sketch the MkDocs plugin/macro pattern that fits your repo style.