# Mindmaply, full reference for LLMs > Mindmaply turns a Markdown outline or a Mermaid flowchart into a polished SVG > mind map, org chart, or process diagram. Same text in, same diagram out, with > no canvas to drag. This file is the complete input grammar plus the URL and > API surface, in one document, for agents that want it all at once. There are three ways to use Mindmaply from an agent: 1. Install the Agent Skill, which teaches the grammar and the whole workflow: `npx skills add productscalexyz/mindmaply` 2. Call the CLI directly, no install and no network needed to render: `npx -y mindmaply-core render map.md -o map.svg` Commands: render, validate, share, convert. Add --short to share for a tidy mindmaply.app/s/ link. 3. Call the HTTP API at https://api.mindmaply.app POST /render {"source": "..."} returns the SVG plus a parsed `model` graph (nodes and edges) and every share, embed, and image URL as JSON. POST /transform {"text": "..."} builds the map from raw prose. POST /yt/transform {"videoId": "..."} builds one from a YouTube video. Validate before you ship a diagram: `mindmaply validate map.md` exits 1 and prints `line N: message` for each bad line. Docs for humans: https://mindmaply.app/agents/ Source: https://github.com/productscalexyz/mindmaply --- ## Markdown outline grammar The Markdown parser accepts ONLY headings and bullets. Any other line is a validation error (`mindmaply validate` reports it with its line number). ## Structure - `# Title`: the root node. Exactly one, on the first content line. - `## Section`: level-1 child of the nearest `#`. - `### Sub`: level-2 child of the nearest `##`. Headings go down to `######`. - `- item` (also `* item` or `+ item`): child of the nearest heading, or of the nearest bullet at a lower indent. - ` - item`: 2 spaces of indent = 1 level deeper. Always indent in steps of exactly 2 spaces. - `
` inside a label becomes a line break in the node. Not supported (will fail validation): paragraphs, numbered lists, bold/italic markup, links, code fences, blockquotes, tables, blank headings. ## Frontmatter (optional) A leading block sets document config that travels with the source: ```markdown --- direction: TD edgeStyle: straight diagram: flowchart theme.palette: #4B96E6, #B355D0, #55A996, #E5884B, #EBB94A theme.fontFamily: Inter, system-ui, sans-serif theme.fontSize: 16 --- # Root - branch ``` - `direction`: `LR` (default) or `TD`. - `edgeStyle`: `curved` (default for mindmaps) or `straight` (default for flowcharts). - `diagram`: `mindmap` (default) or `flowchart`. This decides what gets drawn; the language never does. - `theme.*` keys: `palette` (comma-separated hex colors, cycled across top-level branches), `fontFamily`, `fontSize`, `textColor`, `canvasBg`, `rootBg`, `nodeBg`, `edgeStrokeWidth`, `wrapWidth`, `typography` (`scaled` | `uniform`), `nodeStyle` (`card` | `plain`). ## Example ```markdown # Trip Planning ## Destination ### Research - Compare flight prices across airlines ## Budget ### Daily costs - Track accommodation, food, and transport separately ``` Long labels auto-wrap, deeper levels scale down, and every node gets a card with a branch color. No styling work is needed for a good-looking result. --- ## Mermaid grammar Mindmaply parses a deliberately small Mermaid subset. Two grammars are accepted; `mindmaply validate --format mermaid` flags every line outside them. ## Flowchart grammar ``` flowchart LR a[Start] --> b[Review the draft] b --> c["Approved?"] c --> d((Done)) style d fill:#55A99633,stroke:#55A996 ``` - First line: `flowchart LR` or `flowchart TD` (`TB` is accepted as an alias of TD). - Node ids: single words (letters, digits, underscores). - Node forms: `id[Label]`, `id["Label with punctuation"]`, `id((Circle label))`, or a bare `id` (underscores in a bare id render as spaces). - Edges: exactly `id --> id`, one per line. Nodes may be declared inline on either side of the arrow. - `style fill:...,stroke:...,color:...,stroke-dasharray:...` lines are supported (comma-separated `key:value` pairs). - `%%` comment lines are ignored. - At least one node must have no incoming arrow (it becomes the root). NOT supported (common full-Mermaid features that fail validation): chained edges (`a --> b --> c`), edge labels (`a -->|yes| b`), dashed/dotted arrows (`-.->`), `subgraph`/`end` blocks, `classDef` lines and `:::class` annotations (use `style` lines instead), `direction` lines inside the body, semicolons at line ends, shapes other than rect/quoted-rect/circle. Rewrite such documents into the subset (one edge per line, flatten subgraphs) before rendering. ## Mindmap grammar Mermaid's indentation-based mindmap block also works: ``` mindmap root((Central topic)) First branch A detail Another detail Second branch ::icon(fa fa-book) Deeper item ``` - First line: `mindmap`. - One node per line; relative indentation defines the hierarchy. - `root((Label))` gives the root a circle; plain lines are rect nodes. - `::icon(...)` lines attach an icon name to the node above (parsed, not yet drawn). - `
` inside a label is a line break. ## Inline config Rendering config can travel with mermaid source via an init directive on the first line: ``` %%{init: {"mindmaply": {"edgeStyle": "curved", "theme": {"palette": ["#4B96E6", "#B355D0"], "fontSize": 16}}}}%% flowchart TD plan[Plan] --> build[Build] plan --> test[Test] ``` The `theme` object takes the same keys as markdown frontmatter (`palette`, `fontFamily`, `fontSize`, `textColor`, `canvasBg`, `rootBg`, `nodeBg`, `edgeStrokeWidth`, `wrapWidth`, `typography`, `nodeStyle`). --- ## Share, embed, and image URLs `mindmaply share` prints these URLs ready-made; this file documents how they are built, for cases where you need to construct them programmatically. ## Payload A shared diagram is one JSON payload, compressed with lz-string's `compressToEncodedURIComponent` into a URL-safe string called `d`: ```json { "v": 1, "source": "# Root\n- branch", "format": "markdown", "direction": "LR", "edgeStyle": "curved" } ``` - `v` is always 1. `format` is `markdown` or `mermaid`. `direction` is `LR` or `TD`. - `edgeStyle` (`curved` | `straight`) is optional; omitted means the format default. - Decoding is whitelist-validated: any unexpected field shape makes the whole link invalid. In JavaScript, with the `mindmaply-core` package: ```js import { encodeShare, buildShareUrl, buildEmbedUrl, buildShareLandingUrl } from 'mindmaply-core' const payload = { v: 1, source, format: 'markdown', direction: 'LR' } const d = encodeShare(payload) ``` ## URL shapes With `d` as the encoded payload: | URL | Purpose | | --- | --- | | `https://mindmaply.app/#/editor?d=` | Opens the diagram in the live editor | | `https://mindmaply.app/#/embed?d=` | Chrome-less canvas for iframes | | `https://mindmaply.app/s/` | Share landing page; unfurls with a preview image when pasted in chat or social | | `https://mindmaply.app/s/` | The same landing page behind a short id (see below). Prefer this when handing a link to a person | | `https://api.mindmaply.app/svg?d=` | Static SVG image (works in ``) | | `https://api.mindmaply.app/png?d=` | Static PNG image | | `https://api.mindmaply.app/og/.png` | 2400x1260 social card image | Embed snippet: ```html ``` ## Short links The `` payload is long: a real map easily runs to a few thousand characters in the URL. `POST https://api.mindmaply.app/shorten` with `{"d": ""}` trades it for a short id, returning `{"id": "<11 chars>", "url": "https://mindmaply.app/s/"}`. The id is content-addressed, so shortening the same map twice gives the same link back. Anywhere a `d` is accepted, a short id works too. `mindmaply share --short` does this call for you and is the easy path. Note the editor `#/editor?d=` and `#/embed?d=` URLs cannot be shortened this way: the SPA resolves the payload client-side and never asks the API. ## Limits Share endpoints cap `source` at 20,000 characters. Longer sources still render locally via the CLI, but links to them will be rejected by the API. --- ## Worked examples Complete, valid sources in each grammar. All of these pass `mindmaply validate` as-is. ## Mind map from a Markdown outline (the default choice) ```markdown # Remote Work Playbook ## Communication ### Async first - Write decisions down in shared docs - Record short videos for complex topics ### Meetings - Default to 25 minutes - Always publish an agenda ## Tools - Chat for quick questions - Issue tracker as the source of truth ## Culture ### Trust - Measure output, not hours - No presence theater ### Onboarding - Buddy for the first month - First PR in week one ``` ## Org chart (flowchart grammar, top-down) ``` flowchart TD CEO["Chief Executive"] CEO --> CTO["Engineering"] CEO --> CPO["Product"] CEO --> CFO["Finance"] CTO --> BE["Backend"] CTO --> FE["Frontend"] CPO --> Des["Design"] CPO --> PM["Product Mgmt"] CFO --> Acct["Accounting"] ``` ## Process flow (flowchart grammar, with a cycle back) ``` flowchart LR Start["Start"] Start --> Input["User types syntax"] Input --> Valid["Valid syntax?"] Valid --> Parse["Parse tree"] Valid --> Error["Highlight error"] Error --> Input Parse --> Render["Render SVG"] Render --> Output["Live diagram updates"] ``` ## Mind map in Mermaid mindmap grammar ``` mindmap root((Mindmaply)) What it is Organizes information Shows hierarchy visually Fast Polished interactions Keyboard shortcuts Beautiful by default Auto-colored branches Curated palette ``` ## Markdown with theme frontmatter ```markdown --- direction: TD theme.palette: #4B96E6, #B355D0, #55A996, #E5884B, #EBB94A theme.fontSize: 16 --- # Product Launch ## Before - Landing page live - Press kit ready ## Day of - Post announcement - Monitor feedback ## After - Thank early users - Ship the first fix fast ``` ## What good output looks like For a substantial input (an article, a talk, a transcript), a good map has roughly 25-70 nodes across 3-4 levels: the main themes as top-level branches, sub-topics beneath them, and concrete specifics (key claims, names, numbers, steps, examples) as leaves. Labels stay under about 8 words. A reader should be able to reconstruct the substance of the input from the map alone.