--- title: Markdown that renders everything slug: primitives-showcase order: 20 type: doc description: Code, Mermaid and draw.io diagrams, tabs, callouts, and rich media — every content primitive, rendered beautifully on one page. seoTitle: Markdown docs with draw.io & Mermaid diagrams, code and media seoDescription: Markdown-based documentation that renders syntax-highlighted code, Mermaid and draw.io diagrams, tabs, callouts, and embedded media natively — with a built-in draw.io editor that runs offline. llmSummary: "Live showcase of every Markdown content primitive DSR Docs renders natively: headings, emphasis, lists, Shiki-highlighted code, GitHub-style alerts, tabs, GFM tables, zoomable images with editor-set sizing, self-hosted/YouTube/Vimeo/Loom video, an audio directive, Mermaid diagrams, allow-listed trusted iframe embeds, and horizontal rules. Drawn diagrams use a built-in draw.io editor vendored into the container and served from the site's own origin (CSP connect-src 'self', verified offline by a test); a diagram is stored as an SVG carrying its own draw.io source, so it renders as a plain image for readers, survives PDF/HTML export, print and search, and reopens for editing with no second copy. Confluence exports whose diagrams arrive as fenced drawio XML blocks are converted to those SVGs on import. Author once in plain Markdown plus a few natural extensions; it renders on your brand everywhere. Links out to the one-engine concept guide and the multi-spec use case." visibility: public copyright: © 2026 DSR Corporation icon: Sparkles faq: - q: What can DSR Docs render from plain Markdown? a: Syntax-highlighted code, GitHub-style alerts, tabbed examples, GFM tables, zoomable images with editor-set sizing, video and audio, Mermaid diagrams, allow-listed embeds, and the ordinary headings, lists and emphasis. You author Markdown plus a few natural extensions; the renderer does the rest, styled to your brand. - q: Does DSR Docs support Mermaid diagrams in documentation? a: Yes, natively. A Mermaid code fence renders as a live diagram on the page — flowcharts, sequence diagrams and the rest — with no external service and no image export step. - q: Can I embed video and audio in a documentation page? a: Yes. Self-hosted MP4, YouTube, Vimeo and Loom all embed from standard Markdown image syntax, and audio has its own directive that renders native player controls — because a narration clip is primary content, not a figure that happens to play sound. - q: Can I embed an external site or widget in the docs? a: Yes, but only from origins an admin has put on a trusted-origin allow-list. Anything else renders a blocked-embed warning instead of loading the URL, so an author cannot accidentally embed a malicious site. - q: Do I need MDX or custom React components? a: No. Everything on this page is plain Markdown with a handful of directives, so writers stay in Markdown and the output still carries your brand's colors, fonts and spacing. - q: Can I draw diagrams in DSR Docs, or only write them as code? a: Both. Mermaid renders diagrams written as code in a fenced block, and the draw.io editor is built in for diagrams you would rather draw with a mouse. A drawn diagram is saved as an SVG that carries its own source inside it, so it opens again for editing with no second file to keep in step. - q: Do draw.io diagrams work offline or in an air-gapped install? a: Yes. The editor is vendored into the container and served from your own origin, with hosted-product plugins and cloud-storage connectors stripped out and a Content-Security-Policy whose connect-src is 'self'. A test drives the real editor through a real diagram and fails on a single off-origin request, so the guarantee is checked rather than asserted. - q: Do diagrams from a Confluence export survive the migration? a: Yes. Confluence exports carry diagrams as fenced blocks of draw.io XML, which most tools show as raw markup. DSR Docs converts them once on import, using the same editor that draws them, so they arrive as pictures that still open for editing. --- # Markdown that renders everything DSR Docs is Markdown-based documentation, so plain Markdown goes in. What comes out is syntax-highlighted code, live diagrams, tabbed examples, callouts, zoomable images, embedded video and audio — all styled to your brand, all on this one page. This isn't a feature list; it's the renderer running. Scroll through and see for yourself. ## Headings Standard Markdown headings — `#` through `######`. They build the in-page Table of Contents on the right rail. Anchor links are emitted for each. ```markdown ## Section heading ### Subsection #### Smaller subsection ``` ## Paragraphs and inline emphasis Just write text. **Bold**, *italic*, ~~strikethrough~~, `inline code`, and [external links](https://example.com) all work via standard Markdown. ```markdown **Bold**, *italic*, ~~strikethrough~~, `inline code`, [link](https://example.com). ``` ## Lists Unordered, ordered, and nested — all standard CommonMark. * First bullet * Second bullet * Nested item * Another nested item * Third bullet 1. Ordered item 2. Another ordered item 3. And one more ## Code blocks Fenced code blocks with a language tag get syntax highlighting via Shiki. The header carries a language label and a copy-to-clipboard button. ```typescript type PageEntry = { slug: string; title: string; order: number; type: "doc" | "api-operation" | "api-spec"; description: string; path: string; }; function firstPageOf(domain: DomainEntry): PageEntry | null { return [...domain.ungroupedPages, ...domain.groups.flatMap((g) => g.pages)][0] ?? null; } ``` ```python from dataclasses import dataclass @dataclass class Page: slug: str title: str order: int = 999 pages = [Page(slug="intro", title="Introduction"), Page(slug="api", title="API")] pages.sort(key=lambda p: p.order) ``` ```bash docker run -d \ -p 8080:8080 \ -v "$PWD/content:/data/content" \ --name docs \ registry.example.com/docs:latest ``` Source for the TypeScript block: ````markdown ```typescript type PageEntry = { slug: string; title: string; order: number }; ``` ```` ## Alerts (GitHub-flavored) GitHub-style blockquote alerts cover the common callout patterns. Eight flavors, each with its own color and icon — pick the one that matches intent: `NOTE` · `TIP` · `INFO` · `IMPORTANT` · `SUCCESS` · `WARNING` · `CAUTION` · `DANGER`. > [!WARNING] > Callouts carry intent at a glance. Use them sparingly — a page where everything shouts says nothing. Source: ```markdown > [!WARNING] > Callouts carry intent at a glance. Use them sparingly. ``` Swap the keyword inside `[!…]` to change the flavor. Every flavor uses the same `> [!FOO]` syntax — no further markup needed. ## Tabs For showing the same content across multiple variants — languages, package managers, OS — use the `:::tabs` directive. **Four colons** outer, **three colons** inner. ::::tabs :::tab{label="cURL"} ```bash curl -X POST https://api.example.com/v1/widgets \ -H "Authorization: Bearer $TOKEN" \ -d '{"name": "demo"}' ``` ::: :::tab{label="JavaScript"} ```js await fetch("https://api.example.com/v1/widgets", { method: "POST", headers: { Authorization: `Bearer ${token}` }, body: JSON.stringify({ name: "demo" }), }); ``` ::: :::tab{label="Python"} ```python import requests requests.post( "https://api.example.com/v1/widgets", headers={"Authorization": f"Bearer {token}"}, json={"name": "demo"}, ) ``` ::: :::: Source: ````markdown ::::tabs :::tab{label="cURL"} ```bash curl … ``` ::: :::tab{label="JavaScript"} ```js await fetch(…); ``` ::: :::: ```` ## Tables Standard GFM tables. Pipes, headers, and alignment. | HTTP method | Idempotent? | Used for | | ----------- | :---------: | --------------------------- | | GET | yes | Retrieving a resource | | POST | no | Creating, RPC-style actions | | PUT | yes | Replacing a resource | | PATCH | no | Partial update | | DELETE | yes | Removing a resource | ## Images Standard Markdown image syntax. The renderer wraps it in a clickable zoom overlay — click to see full-size with pan + keyboard shortcuts (`+`, `-`, `0`, arrow keys, `Esc`). ![ACME logo](/branding/acme-logo.svg) ```markdown ![ACME logo](/branding/acme-logo.svg) ``` ### Sizing The image dialog in the rich editor (Insert → Image, or click an existing image and pick **Edit**) has dedicated **Width** and **Height** fields. They get encoded into the Markdown title slot — so an image sized through the editor round-trips as plain CommonMark and stays editable from any text editor. ![Sized to 96 px in the editor](/branding/acme-logo.svg "96") ```markdown ![Sized to 96 px in the editor](/branding/acme-logo.svg "96") ![Hard cap 200×160](/branding/acme-logo.svg "200x160") ``` * **Width only** (`"96"`) — caps the rendered width; height scales proportionally. * **Width × height** (`"200x160"`) — hard caps on both dimensions. * Clearing both fields restores the natural size. * The same `title` slot serves regular captions when it isn't a pixel count — a caption uses `"some text"`, a sized image uses `"320"` or `"320x240"`. ## Video The `Media` component branches on URL: same syntax for self-hosted MP4, YouTube, Vimeo, and Loom. No separate directive. ### Self-hosted MP4 ![A short demo clip](/demo/sample.mp4) ```markdown ![A short demo clip](/demo/sample.mp4) ``` ### YouTube Any `youtube.com/watch?v=...` or `youtu.be/...` URL renders through the privacy-enhanced `youtube-nocookie.com` embed. ![Big Buck Bunny — the open-movie short used as a standard test reel.](https://www.youtube.com/watch?v=aqz-KE-bpKQ) ### Vimeo A standard `vimeo.com/` URL becomes the `player.vimeo.com` embed. ![The Mountain — a time-lapse from Vimeo's staff-picks era.](https://vimeo.com/22439234) ### Loom Loom share links resolve to the `loom.com/embed/...` endpoint automatically. ![A Loom walkthrough — share links are rewritten to the embed endpoint automatically.](https://www.loom.com/share/912e89a68ccc42c5ab5096fec7cd63d6) ## Audio Audio has its own directive — `:::audio{}` — separate from `![alt](url)` because a podcast clip or narration is primary content, not a figure that happens to play sound. It renders as a native `