{"slug": "show-hn-yantra-interactive-step-by-step-diagrams-as-one-offline-html-file", "title": "Show HN: Yantra – Interactive step-by-step diagrams as one offline HTML file", "summary": "Yantra, an open-source diagram tool from developer Niyankhadka, converts a short JSON description into interactive architecture diagrams, sequence diagrams, flowcharts, state machines, ER diagrams, org charts or mind maps and writes a single HTML file that works offline with no network requests. The tool lays out nodes and routes edges automatically with no coordinates in the JSON, runs a validator that reports broken references, overlaps, edges through cards and label collisions with stable codes an agent can fix, and is usable from the command line, from coding agents via an MCP server, from a browser playground or from Python; it requires Node.js 20.19 or later (22.12 or later on Node 22) and installs via npm as @niyankhadka/yantra or via pip as niyankhadka-yantra.", "body_md": "**Interactive, step-by-step diagrams and one-page answers, shipped as one offline HTML file.**\n\n[**Website**](https://yantra.nbk.com.np/) ·\n  [**Docs**](https://yantra.nbk.com.np/docs/) ·\n  [**Playground**](https://yantra.nbk.com.np/playground/) ·\n  [**Examples**](https://github.com/niyankhadka/yantra/tree/main/examples) ·\n  **Changelog**\n\nYantra is an open-source diagram tool that turns a short JSON description into an\ninteractive architecture diagram, sequence diagram, flowchart, state machine, ER diagram,\norg chart or mind map, or into a one-page answer with charts. It lays the diagram out, routes\nthe edges, checks the result with a validator and writes **one HTML file that works\noffline**, with a walkthrough readers can step through. Use it from the command line, from\ncoding agents through MCP, from any AI chat through the browser playground, or from Python.\n\n- **No boxes to place.** Layout, edge routing and label placement are automatic; there are\nno coordinates in the JSON.\n- **A story, not just a picture.** Steps highlight the cards and edges involved, with a\ndescription for each, so a reader can follow a request, a process or a decision.\n- **Checked before anyone sees it.** The validator reports broken references, overlaps,\nedges through cards and label collisions, each with a stable code an agent can fix.\n- **One file to share.** The output makes no network requests: email it, attach it to a\nticket or open it from a USB stick. SVG, PNG and Markdown exports are there too.\n\nOne JSON format covers these kinds of diagram. Each picture links to its example.\n\n| **Architecture and flow** | **Sequence** | **State machine** | \n| **ER and class diagrams** | **Trees and org charts** | **Mind maps** | \n| **Nested groups** | **Answer pages** | **Chart cards, dark theme** | \n\nAlso: drill-down from an overview into detail diagrams, charts on answer pages, and modes\n(for example production against local). Open any of them in the\n[playground](https://yantra.nbk.com.np/playground/) from **Load an example**.\n\nYantra needs **Node.js 20.19 or later** (22.12 or later on Node 22).\n\n```\nnpm i -g @niyankhadka/yantra      # the `yantra` command, with a prebuilt viewer\nyantra new diagram.json           # a starter diagram (--page for an answer page)\nyantra validate diagram.json      # schema, references, story and rendered geometry\nyantra build diagram.json         # -> diagram.html, works offline\n```\n\n| Without installing | Python | Set up your coding agent | \n|---|---|---|\n| `npx @niyankhadka/yantra build diagram.json` | `pip install niyankhadka-yantra` | `npx @niyankhadka/yantra init` | \n\nA first diagram, step by step:\n[Install and your first diagram](https://yantra.nbk.com.np/docs/guides/first-diagram/).\n\n```\n{\n  \"meta\": { \"title\": \"Checkout\", \"description\": \"How an order is paid and stored.\" },\n  \"nodes\": [\n    { \"id\": \"web\", \"type\": \"client\", \"data\": { \"title\": \"Web app\", \"subtitle\": \"Customer checkout\" } },\n    { \"id\": \"api\", \"type\": \"service\", \"data\": { \"title\": \"Orders API\", \"tech\": \"Go\" } },\n    { \"id\": \"db\", \"type\": \"data\", \"data\": { \"title\": \"Orders DB\", \"tech\": \"PostgreSQL\", \"icon\": \"database\" } }\n  ],\n  \"edges\": [\n    { \"id\": \"web-api\", \"source\": \"web\", \"target\": \"api\", \"label\": \"POST /orders\" },\n    { \"id\": \"api-db\", \"source\": \"api\", \"target\": \"db\", \"label\": \"INSERT order\" }\n  ],\n  \"steps\": [\n    { \"title\": \"Overview\" },\n    { \"title\": \"Submit\", \"highlightNodes\": [\"web\", \"api\"], \"highlightEdges\": [\"web-api\"] },\n    { \"title\": \"Persist\", \"highlightNodes\": [\"api\", \"db\"], \"highlightEdges\": [\"api-db\"] }\n  ]\n}\n```\n\nSave it as `checkout.json`, then run `yantra validate checkout.json` and\n`yantra build checkout.json`. The rules, budgets and every validation code are in\n[Authoring diagrams](https://yantra.nbk.com.np/docs/authoring/); answer pages are covered in\n[Answer pages](https://yantra.nbk.com.np/docs/pages/).\n\n**Coding agents** (Claude Code, Cursor, Codex, Antigravity). One command adds the Yantra\nskill and MCP server to your project, so the agent can read your code and draw it:\n\n```\nnpx @niyankhadka/yantra init          # the agents whose folders exist here, else Claude Code\nnpx @niyankhadka/yantra init --all    # Claude Code, Cursor, Codex and Antigravity\n```\n\n`init` writes only inside the project, never overwrites a file it did not write, merges MCP\nconfigs and is safe to run again (`--dry-run` shows what it would do). Guide:\n[Diagrams from your codebase](https://yantra.nbk.com.np/docs/guides/coding-agents/).\n\n**AI chats** (Claude.ai, ChatGPT, Gemini and others). Nothing to install: open the\n[playground](https://yantra.nbk.com.np/playground/), press **Copy prompt for your chat** and\npaste it into the chat. Paste the JSON it answers with back into the playground to validate\nit, see it and download it. The button follows the editor: with a diagram loaded it copies\nthe diagram too, and with validation findings it asks the chat to fix them. Everything runs\nin your browser. Guide: [Use with Claude.ai, ChatGPT and any chat](https://yantra.nbk.com.np/docs/guides/chat/).\n\n**Existing diagrams.** `yantra import` reads Mermaid, PlantUML, draw.io / diagrams.net and\nVisio `.vsdx` files and validates the result. Guide:\n[Import Mermaid, PlantUML, draw.io and Visio](https://yantra.nbk.com.np/docs/guides/import/).\n\n**Python.** Build payloads in Python and let the CLI validate and build them. Guide:\n[Python SDK](https://yantra.nbk.com.np/docs/guides/python/).\n\n- **Layouts:** layered layout with orthogonal edge routing; trees, org charts, decision\ntrees and mind maps; groups nested up to six levels; an optional manual layout.\n- **Diagram kinds:** flow and architecture, sequence (lifeline) view of the same payload,\nstate machines with fork / join and regions, ER and UML class diagrams, chart cards.\n- **Walkthroughs:** scenarios with steps, autoplay, camera follow and a present mode;\nfolding for big diagrams; drill-down into detail diagrams up to eight levels.\n- **Answer pages:** the conclusion first, then blocks such as points, metrics, charts,\ncompare, table, timeline, FAQ, checklist, gantt, matrix and embedded diagrams.\n- **Charts:** bar, column, line, area, pie and donut charts, sparklines, gantt plans and 2x2\nor risk heat-map matrices, drawn as inline SVG with no chart library.\n- **Sharing:** one offline HTML file; SVG, PNG and Markdown exports; view state in the URL\nhash; light and dark themes; print styles; your own logo.\n- **Languages and accessibility:** 18 interface languages, right-to-left layout for Arabic,\nHebrew, Persian and Urdu, full keyboard control and contrast tests on the theme.\n- **For agents:** a validator with stable codes, a CLI, an MCP server (stdio and Streamable\nHTTP), an agent skill and a Python SDK.\n\n## **CLI reference**\n\n| Command | What it does | \n|---|---|\n| `yantra validate <file.json> [--json] [--lang xx]` | Check schema, references, story and rendered geometry. Exits with code 1 on errors. | \n| `yantra build <file.json> [-o out.html] [--force]` | Validate, then write a single offline HTML file. | \n| `yantra export <file.json> -f svg\\|md [-o file]` | Static SVG (diagrams) or Markdown (diagrams and pages). | \n| `yantra screenshot <file.json\\|page.html> [-o out.png]` | PNG through the local Chrome or Edge ( `YANTRA_BROWSER` overrides). | \n| `yantra new <file.json> [--page]` | Write a starter diagram or answer page. | \n| `yantra import <file> [-o out.json]` | Convert Mermaid, PlantUML, draw.io or Visio, then validate. | \n| `yantra examples [name] [-o file]` | List the built-in examples, or copy one. | \n| `yantra init [--claude] [--cursor] [--codex] [--antigravity] [--all]` | Set up a project for coding agents: skill, MCP server, rules. Also `[--dir path] [--force] [--dry-run] [--json] [--windows\\|--posix]` . | \n| `yantra schema [diagram\\|page]` | Print the JSON Schema for diagrams or answer pages. | \n| `yantra docs [authoring\\|pages\\|mermaid\\|import\\|agents]` | Print a guide. | \n| `yantra mcp [--http]` | Start the MCP server on stdio, or over Streamable HTTP with `--http [--port 8787] [--host 127.0.0.1]` . | \n| `yantra dev` | Start the live viewer at [http://localhost:3000](http://localhost:3000) (from a clone after`npm install` , or with`vite` installed next to the package). | \n\n| Option | Commands | Meaning | \n|---|---|---|\n| `--json` | validate | Machine-readable output. | \n| `--lang xx` | validate | Messages in a built-in language ( `es` ,`ja` ,`ar` ...);`auto` uses`meta.lang` . Codes stay the same. | \n| `--force` | build | Build even when validation reports errors. | \n| `--theme light\\|dark` | export, screenshot | Theme to draw. | \n| `--mode id` | export | One of the diagram's modes. | \n| `--view flow\\|sequence` | export, screenshot | Flow graph or sequence diagram. | \n| `--step n` | export, screenshot | Highlight walkthrough step `n` (1-based). | \n| `--level id` | export, screenshot | A detail diagram (drill-down level) instead of the overview. | \n| `--all-levels` | export ( `-f md` ) | Append every detail diagram after the overview. | \n| `--collapsed a,b` | build, export, screenshot | Open with these subtrees or groups folded, instead of `meta.layout.collapsed` . | \n| `--expand-all` | build, export, screenshot | Open with nothing folded. | \n| `--depth n` | build, export, screenshot | Fold to depth `n` :`n` levels of boxes or tree levels stay open. | \n| `--focus group` | screenshot | Zoom the camera to a group, unfolding it and the boxes around it. | \n| `--width` ,`--height` | screenshot | Viewport size; `--width 390` shows a page at phone width. | \n| `--from mermaid\\|drawio\\|plantuml\\|visio` | import | Force the source format. | \n| `--page n\\|name` | import | draw.io or Visio page to import (default: the first). | \n| `--title \"...\"` | import | Title of the imported diagram. | \n| `--all` | import | Import every page or diagram block. | \n\nFrom a clone without `npm link`, use `node bin/yantra.js` in place of `yantra`.\n\n## **MCP server**\n\n`yantra mcp` (or `node mcp/server.js`) speaks MCP over stdio; `yantra init` registers it for\nyour agents. Tools: `yantra_get_schema`, `yantra_list_examples`, `yantra_get_example`,\n`yantra_validate`, `yantra_build`, `yantra_export`, `yantra_import`, `yantra_import_mermaid`\nand `yantra_screenshot`. File access is sandboxed to `YANTRA_INPUT_ROOT` and\n`YANTRA_OUTPUT_ROOT` (both default to the server's working directory).\n\n`yantra mcp --http` serves the same tools over Streamable HTTP for clients that connect by\nURL, such as Claude.ai and ChatGPT connectors. You host it; see\n[Remote MCP server](https://yantra.nbk.com.np/docs/remote-mcp/). Manual setup for every agent\nand Claude Desktop: [Coding agents](https://yantra.nbk.com.np/docs/agents/).\n\n## **Viewer keyboard shortcuts**\n\nPress `?` in a diagram to see the keys that work there.\n\n| Key | Action | Key | Action | \n|---|---|---|---|\n| `→` /`Space` ,`←` | Next / previous step | `Home` /`End` | First / last step | \n| `P` | Play / pause | `C` | Camera follows steps | \n| `S` | Collapse the walkthrough | `1` -`9` | Switch scenario | \n| `V` | Flow / sequence view | `M` | Next mode | \n| `I` | Inspector | `L` | Roles legend | \n| `T` | Light / dark | `F` | Full screen | \n| `X` | Fold / unfold the selected branch | `1` -`6` ,`0` | Fold to depth, open everything ( `Shift` with several scenarios) | \n| `D` | Open the card's detail diagram | `G` | Zoom to the selected card's group | \n| `+` /`-` ,`R` | Zoom, fit to screen | `Esc` | Clear selection, then back up a level | \n\nThe view state is mirrored in the URL hash, for example\n`#level=payments&step=3&mode=dev&view=sequence&theme=dark`, so a link reopens the same view.\n\n[`examples/`](https://github.com/niyankhadka/yantra/tree/main/examples) holds 25 diagrams,\n13 answer pages and 7 chart pages, plus import samples for Mermaid, PlantUML, draw.io and\nVisio. Every example validates with no warnings. `yantra examples` lists them and\n`yantra examples oauth-login -o oauth.json` copies one. Companies and data in the examples\nare fictional.\n\nThe reference pages are the files in [`docs/`](https://github.com/niyankhadka/yantra/tree/main/docs),\nso they match the release you are reading.\n\n```\ngit clone https://github.com/niyankhadka/yantra.git\ncd yantra\nnpm install\nnpm run dev          # viewer with every example at http://localhost:3000\nnpm test             # Node test suite\nnpm run dev:site     # website and playground at http://localhost:3001/\n```\n\nPython SDK tests: `pip install -e python/`, then\n`python -m unittest discover -s python/tests`. Setup, layout of the repository and the\nrules the tests enforce are in the\n[contributing guide](https://github.com/niyankhadka/yantra/blob/main/CONTRIBUTING.md).\n\n- [Contributing guide](https://github.com/niyankhadka/yantra/blob/main/CONTRIBUTING.md) : setup, tests and pull requests.\n- [Support](https://github.com/niyankhadka/yantra/blob/main/SUPPORT.md) : where to ask questions and report bugs.\n- [Security policy](https://github.com/niyankhadka/yantra/blob/main/SECURITY.md) : report vulnerabilities privately.\n- [Code of conduct](https://github.com/niyankhadka/yantra/blob/main/CODE_OF_CONDUCT.md) .\n\nIf Yantra is useful to you, you can [buy me a coffee](https://buymeacoffee.com/niyankhadka),\nstar the repository, or keep the \"Made with Yantra\" badge in your diagrams\n(`meta.watermark: false` hides it).\n\n[MIT](https://github.com/niyankhadka/yantra/blob/main/LICENSE) © niyankhadka. The licence\ncovers the code; the Yantra name and logo are covered by the\n[trademark policy](https://github.com/niyankhadka/yantra/blob/main/TRADEMARKS.md).", "url": "https://wpnews.pro/news/show-hn-yantra-interactive-step-by-step-diagrams-as-one-offline-html-file", "canonical_source": "https://github.com/niyankhadka/yantra", "published_at": "2026-10-21 19:49:14+00:00", "updated_at": "2026-10-21 20:13:08.584345+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "agent-protocols", "ai-tools"], "entities": ["Yantra", "Niyankhadka", "Claude Code", "Cursor", "Codex", "Antigravity", "Node.js", "PostgreSQL"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/show-hn-yantra-interactive-step-by-step-diagrams-as-one-offline-html-file", "markdown": "https://wpnews.pro/news/show-hn-yantra-interactive-step-by-step-diagrams-as-one-offline-html-file.md", "text": "https://wpnews.pro/news/show-hn-yantra-interactive-step-by-step-diagrams-as-one-offline-html-file.txt", "jsonld": "https://wpnews.pro/news/show-hn-yantra-interactive-step-by-step-diagrams-as-one-offline-html-file.jsonld"}}