Known Limitations

Transparency matters. Here's what the Google platform doesn't let us do — and what we do instead.

Mermaid Toolkit for Google Docs™ runs entirely inside Google Docs™ using Apps Script. While this keeps your data private and requires no external server, it also means we inherit every limitation of the Google Apps Script sandbox and the Docs API. Below are the ones you're most likely to notice.

Checkboxes Cannot Be Auto-Checked

Docs API Import from Markdown Export as Markdown

When importing markdown with task lists (- [x] Done), the add-on creates native Google Docs™ checkboxes. However, the Docs API provides no way to programmatically set a checkbox to the "checked" state. All checkboxes are inserted unchecked.

When exporting, the checked/unchecked state is also invisible to the API — all checkboxes export as - [ ] regardless of their actual state in the document.

Why: The createParagraphBullets API supports the BULLET_CHECKBOX preset but exposes no checkedState field. The bullet object returned by documents.get is identical for checked and unchecked items — the checked state is stored internally and not exposed through any API surface.

Checkbox Workaround Requires Extra API Calls

Docs API Performance

Google Docs™' DocumentApp (Apps Script) has no native checkbox support. To create checkboxes, the add-on must insert plain paragraphs, save the document, then use the separate Docs REST API to convert them into checkbox bullets. This multi-step process adds noticeable latency.

Why: DocumentApp.ListItem supports bullet and numbered glyphs but not checkbox glyphs. The Docs Advanced Service (Docs.Documents.batchUpdate) is the only way to create them.

Slower Performance on Non-Primary Tabs

Docs API Multi-Tab Docs

When working on a tab other than the first tab in a document, operations that require the Docs REST API (like checkbox creation) take significantly longer — typically 5–6 seconds vs ~1 second on the primary tab.

Why: The Docs API's documents.get endpoint doesn't support fetching a single tab by ID. For non-primary tabs, the add-on must request includeTabsContent: true, which returns content for all tabs — even if only one is needed.

Code Blocks Inserted as Tables

DocumentApp Import from Markdown

Google Docs™ has no native "code block" element. 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.

Why: DocumentApp supports paragraphs, tables, and list items. There is no code-block element type, and no way to apply syntax highlighting programmatically.

Diagrams Are Static Images

Apps Script Sandbox All Diagrams

Mermaid diagrams are rendered as PNG images inside Google Docs™. They cannot be interactive, zoomable, or auto-updated when the source changes. To update a diagram, you need to edit the source and re-render it.

Why: Google Docs™ only supports inline images (raster). There is no support for embedded SVG, interactive elements, or live-updating content.

ZenUML Diagrams Not Supported

Apps Script Sandbox ZenUML

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.

Why: Unlike built-in Mermaid diagram types, ZenUML ships as a separate package that must be imported via 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.

List Nesting Not Compatible with Native Markdown

DocumentApp Import from Markdown Export as Markdown

Mermaid Toolkit's Import and Export Markdown features handle nested lists correctly using Google Docs™' nesting levels. However, Google Docs™' native Copy as Markdown and Paste as Markdown do not recognize these nesting levels, resulting in flat (non-nested) output.

Additionally, due to a Google API limitation, checked task list items ([x]) are imported as unchecked — the checked state cannot be set programmatically.

For consistent results, choose one approach and use it throughout your workflow:

Recommended: Use Mermaid Toolkit's Import/Export for all markdown operations
Alternative: Use Google Docs™' built-in Copy/Paste as Markdown. If you choose this route, you can still use Convert All Code to Diagrams and Convert All Diagrams to Code to handle mermaid diagrams, and the Fix Native "Copy as Markdown" tool to repair mangled syntax

Why: ListItem.setNestingLevel() creates visual indentation but not true sub-lists in the internal document structure. Google's native markdown features read the internal structure, not the visual nesting.

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 — Solved

Solved Canvas API All Diagrams

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.

Why this was hard: Browser security policy prevents reading pixel data from a canvas that has rendered foreign content. On top of that, some diagram types (C4) use CSS-driven layouts with 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

Workaround Import from Markdown

If the add-on's import limitations (unchecked checkboxes, table-based code blocks, no table header highlighting) 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

Trade-offs: Native paste doesn't apply our inline code styling, table header highlighting, or automatic diagram rendering. "Paste as Markdown" is only available on paid Google Workspace™ accounts (Business Standard and above, Education Standard and above, and Nonprofits) — it is not available on personal Google accounts or Workspace starter plans. On accounts without this feature, code blocks may not be parsed correctly by Google Docs™, so you may need to handle those manually.

Alternative: Export via Native "Copy as Markdown"

Workaround Export as Markdown

If you need checked checkboxes ([x]) preserved in your exported markdown, you can use Google Docs™' native Copy as Markdown instead:

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

Trade-offs: Google's native "Copy as Markdown" preserves checkbox state but may mangle mermaid syntax (vertical tabs, stray backticks). The Fix tool repairs these issues. This approach gives you a complete round-trip with checked checkboxes intact. Note: "Copy as Markdown" is only available on paid Google Workspace™ accounts.