Developer Overview

A Molkit SVG export is not a flat picture. Depending on the export options you enable, the file 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), and, for animated exports, a scriptable SMIL timeline you can pause, scrub, and step through from plain JavaScript. This guide documents that surface: what the file format gives you, and the host-page code that uses it.

What you need

Each layer is switched on by an option in the export dialog. Enable the ones you plan to use.

Export option	What it adds	Documented at
Theme-aware export	`.mk-*` classes plus a scoped stylesheet, so colors are restylable from your page; includes an automatic dark mode	/developer/theming/
Embed chemistry metadata	`data-mk-*` attributes (formula, SMILES, per-atom and per-bond chemistry) and a `mk:chemistry` metadata block	/developer/metadata/
Animated SVG export	A SMIL timeline with `data-duration`, `data-breakpoints`, and `data-transitions` stamped on the root	/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 and metadata enabled, 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/animations/: the timeline attributes, pause/scrub/step-through control, reduced motion.
/developer/cookbook/: copy-paste recipes: hover highlights, tooltips from metadata, scrubbers, viewers.