Developer Overview

A Molkit SVG export carries up to three layers you can program against: a CSS theming layer (every bond, atom label, and charge is reclassified into stable .mk-* classes with a built-in dark mode), a machine-readable chemistry layer (data-mk-* attributes on the root, on every atom group, and on every bond group, plus an embedded MOL block, 3D conformer, and dipole data), and, for animated exports, a timeline you can pause, scrub, and step through from plain JavaScript. Molkit also ships a ready-made structure widget that reads the chemistry layer. The pages in this guide describe what the file format gives you and the host-page code that uses it.

What you need

Layer	How you get it	What it adds	Documented at
Theming	Theme-aware checkbox in the export dialog	`.mk-*` classes plus a scoped stylesheet, so colors are restylable from your page; includes an automatic dark mode	/developer/theming/
Chemistry metadata	Always embedded in SVG exports from the Export SVG dialog	`data-mk-*` attributes (formula, SMILES, per-atom and per-bond chemistry), a `mk:chemistry` metadata block, 3D conformers, and dipoles, plus an electrostatic potential map when the author made one	/developer/metadata/
Animation	Animated SVG export	A timeline with `data-duration`, `data-breakpoints`, and `data-transitions` stamped on the root: SMIL for molecule animations, CSS `@keyframes` for LaTeX solution animations	/developer/animations/

Dark mode in theme-aware exports follows the OS preference via a prefers-color-scheme media query inside the file. Newer exports also carry class hooks: put mk-dark on the SVG or any ancestor to force dark, or mk-light to force light, which is what sites with their own theme toggle need. SVGs exported before this feature shipped respond only to the media query, so re-export old files if you need the class hooks.

Choosing an embedding method

How you put the file on the page decides what you can do with it. Full trade-offs, sizing, and multi-copy handling are on /developer/embedding/.

Method	Animations	Page CSS reaches inside	Page JS reaches inside	Use it for
`<img src="mol.svg">`	SMIL plays (no control)	No, but the SVG’s own dark media query still applies	No	Plain figures
`<object data="mol.svg">`	SMIL plays	No	Only via same-origin `contentDocument` plumbing	Self-running animations
`<iframe src="mol.svg">`	SMIL plays	No	Only via same-origin `contentDocument` plumbing	Isolated animations
Inline `<svg>` in the page	SMIL plays	Yes	Yes	Anything interactive; the recommended default

Quickstart

Export with theme-aware enabled (chemistry metadata is always included), then paste the file’s contents straight into your page. One element, one line of JS:

<!doctype html>
<html lang="en">
<body>
  <!-- Paste the full contents of your exported .svg file here. -->
  <!-- Root shown abbreviated; a real export carries its styles inside. -->
  <svg id="molkit-nknpn" viewBox="1866 1393 92 100" role="img"
       data-mk-version="1.0" data-mk-formula="C6H6"
       data-mk-smiles="c1ccccc1">
    <style>/* exported .mk-* rules + dark-mode block live here */</style>
    <!-- ...molecule geometry... -->
  </svg>

  <script>
    const svg = document.querySelector('svg[data-mk-version]');
    console.log(svg.dataset.mkFormula); // "C6H6"
  </script>
</body>
</html>

Dark mode needs no code at all: the exported stylesheet flips with the OS setting automatically. Add class="mk-dark" to the SVG (or a parent) to force it on.

The same data-mk-* pattern scales down to parts of the drawing: atom groups carry data-mk-element, data-mk-hybridization, and about twenty other attributes; bond groups carry data-mk-order, endpoints, and stereo flags.

Where to go next

/developer/embedding/: inline vs img vs object, responsive sizing, multiple copies on one page, CSS-bleed resets.
/developer/theming/: the .mk-* class reference, overriding colors, class-based dark mode, fonts.
/developer/metadata/: the data-mk-* schema reference, reading patterns and gotchas, extracting the MOL block.
/developer/widget/: mounting the interactive structure widget, the browser storage it uses, dipole display, the 3D viewer, and electrostatic potential maps.
/developer/animations/: the timeline attributes, pause/scrub/step-through control, reduced motion, and how LaTeX solution exports differ.
/developer/cookbook/: copy-paste recipes: hover highlights, tooltips from metadata, scrubbers, viewers.