How to Build Solution Design Packs with Markdown, Interactive Mermaid Diagrams & OpenAPI

A solution design is never one file. An architect or systems engineer finishes a piece of work holding a design document, two or three diagrams, a data model, a decision log, and an API contract — and every one of those artifacts traditionally requires a different tool to view.

That is the friction. The design lives in a wiki, the diagrams in a drawing tool, the contract in a spec editor, and the version anyone actually reviews is a PDF assembled the night before a stakeholder meeting.

This article walks through keeping the whole pack in one local folder — Markdown for the prose, Mermaid for the diagrams, OpenAPI YAML for the contract — reading it in one place, and distributing it as standalone HTML that opens on any machine.

---

1. What a modern solution design pack is made of

A design pack is five or six artifacts — prose, diagrams, a data model, a decision log and an API contract — that traditionally live in five or six different tools. Keeping them as plain files in one folder is what makes the set reviewable as a unit.

Here is a typical set, and where each piece normally ends up:

Split across four tools, the pack has no single reviewable state. Kept as files in one folder, it has exactly one — and it diffs, branches, and reviews in git like the code it describes.

The catch has always been reading it. A folder of .md and .yaml is the right storage format and the wrong reading experience, which is where a local-first renderer comes in.

---

2. The design document with live diagrams

A Mermaid block inside the Markdown renders as a real diagram with pan, zoom and fullscreen — not a picture, and not a code fence the reader has to compile in their head. The diagram is the same text the design doc is written in, so it diffs in git like the rest of the file.

Open the folder in Prisment and the design document renders as a document: heading hierarchy, tables with real table styling, and — the part that usually forces a second tool — Mermaid blocks rendered as diagrams, with pan, zoom and a fullscreen control.

Both of the diagrams in that screenshot are plain text in the source file. The flowchart is six lines:

flowchart LR
  SF[Storefronts] --> API[Order API]
  API --> Q[(Order events)]
  Q --> ORCH[Orchestrator]
  ORCH --> WMS[Warehouse]
  ORCH --> BIL[Billing]

Which matters less for how it looks than for what happens next time the design changes. A diagram that is text is a diagram you edit in the same pass as the paragraph above it, in the same review, in the same commit — instead of one that quietly goes stale because updating it means finding the original file in someone's drawing tool.

---

3. The API contract, rendered as interactive API docs

One top-level key decides it: a YAML file with openapi: or swagger: at its root renders as browsable API documentation, and any other YAML renders as read-only source. The spec is parsed in your browser, never sent to an external Swagger service.

A .yml or .yaml file in the workspace opens in a read-only viewer. If the file is an OpenAPI or Swagger definition, it renders as browsable API documentation instead of as text:

What decides which view you get is one top-level key. A document with openapi: (OpenAPI 3.x) or swagger: (Swagger 2.0) at the root gets the API-docs treatment and an OpenAPI badge; any other YAML — a pipeline config, a Kubernetes manifest, a half-finished file that does not parse — falls back to a clean read-only text view with a YAML badge. Either way the Copy button gives you the raw source.

Two things worth being precise about:

• The viewer parses the YAML directly, in the browser. It does not send it to an external Swagger hub or validator.
• Operations expand in place. Clicking an endpoint opens its parameters, request body and responses, with schema tables and example payloads.

---

4. Exporting the whole pack for the team

Export the whole folder as All Interlinked Wiki and reviewers get a browsable offline site — every document a page, the OpenAPI file interactive API docs, cross-links rewritten, and a sidebar tree to navigate it. They double-click index.html; there is nothing to install.

When the design is ready for review, you have two audiences:

• The engineers building it want the repository.
• The product manager, enterprise architect, security reviewer and client want to read it.

For the second audience, click Export and choose All Interlinked Wiki:

This produces a ZIP containing:

1. Every .md file as a standalone HTML page with its presentation style applied.
2. The openapi.yaml file as an interactive API documentation page.
3. Working relative links between documents.
4. A navigation sidebar tree for browsing the pack offline.

Unpack the ZIP into an S3 bucket, Cloudflare Pages, or simply hand the ZIP to the reviewer. They double-click index.html and have the entire design pack in front of them — prose, diagrams and API spec — with no tools to install and no server to spin up.

Interlinked Wiki is one of several export shapes, and the others suit different hand-offs — the guide to standalone HTML and offline wiki export compares them.

Related reading

• Live presentation previews for AI CLI agents — when the first draft of the pack is written by Claude Code or Gemini CLI.
• Designing custom document themes — putting your own brand on the pack before you send it.
• Turning raw AI Markdown into presentation-grade HTML — the presentation styles each exported page carries.