Known Limitations
Transparency matters. Here's what the Google platform doesn't let us do — and what we do instead.
Mermaid Toolkit runs entirely inside Google Docs using Apps Script and the DocumentApp API. While this keeps your data private and requires no external server, it also means we inherit every limitation of the Apps Script sandbox and what DocumentApp exposes to Google Workspace add-ons. Below are the ones you're most likely to notice.
Large Documents Can Take Time to Import or Export
Importing or exporting a large document, especially one with many Mermaid diagrams, can take several seconds. The add-on shows a note when an import or export operation runs longer than expected.
documents.currentonly OAuth scope, rich document work goes through Apps Script's DocumentApp API. That API exposes document content as individual paragraphs, list items, tables, text runs, and images rather than one bulk markdown import/export operation. The add-on has to walk that structure and rebuild it carefully so formatting, lists, tables, and Mermaid diagrams survive the round trip.
Checkboxes Are Plain-Text, Not Native Glyphs
Checklist items (- [ ] / - [x]) are imported as ordinary bullet list items whose text starts with a literal [ ] or [x] marker instead of being converted to Google Docs native checkbox glyphs.
DocumentApp API available to Apps Script add-ons has no method for creating native Google Docs checkbox glyphs — no createChecklist(), no GlyphType.CHECKBOX. The only path to native checkboxes is a REST call (Docs.Documents.batchUpdate with BULLET_CHECKBOX) that this add-on no longer uses as it requires the broader documents OAuth scope. The plain-text representation gives a checkbox-like UX using the primitives DocumentApp actually exposes. See the v1.1.0 changelog entry for the full rationale.
Code Blocks Inserted as Tables
When importing markdown with fenced code blocks, the add-on inserts them as single-cell tables with a monospace font and light background — a visual approximation, not a true code block.
DocumentApp has no method for creating Google Docs native Code Blocks (the Insert → Building blocks → Code blocks element), and that feature is only available on some paid Workspace plans and not personal accounts. A single-cell table is the closest way to get a similar visual result.
Very Large Diagrams: Image Size, Resolution, and Stored Source
Google Docs rejects diagram PNGs whose longest side exceeds 5,000 pixels (Invalid image data). The add-on automatically downscales taller or wider exports while keeping aspect ratio, up to that limit.
Resolution and zoom. Because the longest side is capped at 5,000px, a very tall, narrow diagram only gets a limited number of pixels across its width. If you enlarge that image and then zoom Google Docs in (say to 200%), text and thin lines can look soft — the bitmap simply doesn't hold more detail to show. To make the most of the cap, the add-on lays flowcharts out wider and shorter, renders at a higher internal resolution, and applies a light sharpening pass. Even so, a single inline raster image can't behave like a vector at high zoom; for very large diagrams, splitting them into a few smaller ones keeps every part crisp.
Separately, Docs limits image alt description text to about 5,000 characters after encoding — and a long Mermaid definition doesn't fit. When that happens, the add-on stores the full source in this document's hidden properties (no extra permissions) and keeps a short docstore: pointer on the image instead. For these larger diagrams you won't find the source in the image's alt-text field — that's expected. Export as Markdown and Edit Diagram read from the hidden store, so import → export → re-import round trips stay lossless.
insertImage and setAltDescription calls. The editor and Import preview warn when a diagram hits either cap. Source kept in document properties stays with this file only — it isn't copied if you paste the image into another document.
Diagrams Are Static Images
Mermaid diagrams are rendered as PNG images inside Google Docs. They cannot be interactive, zoomable, or auto-updated when the source changes. You can simply use Import from Markdown or Export as Markdown will update the diagram image to match the source.
ZenUML Diagrams Not Supported
ZenUML is an external Mermaid module (@mermaid-js/mermaid-zenuml) that requires ES module loading and explicit registration. The Google Apps Script sandbox uses UMD script loading and its Content Security Policy does not permit dynamic ES module imports, making ZenUML integration infeasible without a server-side component.
import() and registered with mermaid.registerExternalDiagrams(). The GAS iframe's CSP blocks dynamic module imports, and bundling the UMD version introduces significant payload size for a single diagram type.
Solved Challenges
Some browser and platform restrictions looked like deal-breakers — until we found a way around them. These are challenges we've fully solved while keeping everything client-side.
Browser Security vs Diagram Rendering
Mermaid v11 uses <foreignObject> elements in its SVG output. When drawn to an HTML canvas, browsers "taint" the canvas — canvas.toDataURL() throws a security error and the diagram can't be exported as a PNG. Many tools work around this by sending diagram data to a server for rendering, breaking privacy.
We solved this entirely client-side with a multi-pass rendering pipeline:
- Preserve fidelity — try rendering the SVG as-is with
<foreignObject>intact for maximum visual quality - Sanitize — if the canvas is tainted, replace
<foreignObject>elements with pure SVG<text>equivalents, preserving bold, color, and font-size - DOM measurement — for CSS-driven layouts (like C4 diagrams), insert the SVG into a live hidden DOM element, use
getBBox()to measure actual content bounds, then normalize coordinates before rendering
The result: all 25 diagram types render correctly, and your diagram code never leaves your browser.
width: 100% and negative viewBox offsets, which break when SVGs are rendered as static images. The multi-pass pipeline handles both cases without any server involvement.
Workarounds
Some limitations can be worked around using a combination of native Google Docs features and the add-on's tools.
Alternative: Import from Markdown via Native Paste
If the add-on's import limitations (table-based code blocks, plain-text checkboxes) are a problem, you can use Google Docs' native Paste as Markdown feature instead:
- Copy your markdown content
- In Google Docs, use Edit → Paste as Markdown (or Ctrl+Shift+V on some versions)
- Run Convert All Code to Diagrams to render any mermaid code blocks as diagrams
Alternative: Export via Native "Copy as Markdown"
If your document contains native Google Docs checkbox glyphs (for example, items inserted via Google's own Insert → Checklist UI) and you need their checked state in the exported markdown, you can route through Google Docs' native Copy as Markdown instead of the add-on's exporter:
- First, run Convert All Diagrams to Code to turn diagrams back into Mermaid source
- Select all content (Ctrl+A) and use Edit → Copy as Markdown
- Paste into your markdown editor
- If the Mermaid code is mangled, paste it into our Fix Native "Copy as Markdown" tool to repair it
DocumentApp API exposes paragraphs and list items but not the checked/unchecked state of native checkbox glyphs. Google's native Copy-as-Markdown reads the underlying data model directly, so it can preserve that state. The trade-off is that its Mermaid syntax output is often mangled — the Fix tool handles that part. "Copy as Markdown" is available on all Google Docs accounts, including personal ones.