Docs & Code Guide

Embed diagrams in Docsify: runtime rendering, the :size syntax, and zero rebuilds

Docsify is the docs generator that never generates: a small index.html loads your Markdown files in the browser and renders them at view time. There is no build step to freeze anything, which makes it a natural host for a live architecture diagram. Every page view assembles from current sources, so an edited diagram reaches readers subject only to plain HTTP caching. Here is the exact syntax, the sizing trick, and the tradeoff the no-build model carries.

Try it free
6 min readFor teams running lightweight internal docs on Docsify

See it as a diagram

Everything below, as a diagram you can edit. Describe yours and see it in seconds.

146/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

No build step: the page assembles in the browser

Most docs generators compile Markdown to HTML at build time, so what readers see is frozen until the next deploy. Docsify skips that entirely: index.html ships a small runtime that fetches the Markdown file and renders it in the browser on every visit. Change a Markdown file on the server and the next page load shows it; no pipeline runs.

For an embedded diagram this removes even the theoretical staleness a build could add. The Markdown references an image URL, the reader's browser fetches that URL at view time, and Datadef serves it with an ETag from the diagram's last edit and a five minute cache lifetime. Edit the diagram and readers see the new version within minutes, gated only by browser caching, never by a rebuild.

The :size syntax for a diagram that fits

Docsify extends Markdown image syntax with a sizing hint in the title position. Append ':size=WIDTHxHEIGHT' to set both dimensions, or ':size=WIDTH' for width alone with the aspect ratio preserved. Combine it with the render parameters on the image URL itself when you want more pixels for a wide layout: the URL parameters control how many pixels are rendered, the :size hint controls how large they display.

<!-- Display at 800px wide, aspect ratio preserved -->
![Platform architecture](https://datadef.io/api/embed/my-platform-a1b2c3d4 ':size=800')

<!-- Sharp render for wide screens, displayed at 1000x625 -->
![Platform architecture](https://datadef.io/api/embed/my-platform-a1b2c3d4?width=2400&height=1500&scale=2 ':size=1000x625')

HTML and iframes render too

Docsify renders HTML embedded in Markdown, so the interactive form is available as a pasted iframe. Readers pan and zoom the actual diagram, which is the better fit for dense views like zone-grouped platforms or column-level lineage. The image form stays the right default for overview pages, where one request and instant paint matter more.

<iframe
  src="https://datadef.io/embed/my-platform-a1b2c3d4"
  style="width: 100%; height: 460px; border: none;"
  title="Platform architecture"
></iframe>

The tradeoff: runtime rendering and crawlers

The no-build model has a cost worth stating plainly: content renders client-side, so crawlers that do not execute JavaScript see a nearly empty shell. Public docs that need search visibility usually pair Docsify with prerendering or choose a static generator instead. For internal wikis and team docs, where most Docsify sites live, none of this matters and the zero-maintenance model is the draw.

The same reasoning applies to the diagram: on an internal Docsify site, the embed is purely a win. On a public one, the diagram is an image to crawlers either way, so the embed changes nothing for SEO; it just stays correct while a committed screenshot would rot.

Keeping the diagram itself current

Docsify removes the rebuild; the diagram edit remains. When the architecture changes, someone edits the diagram in Datadef, or an agent does: given the server at registry name io.datadef/mcp, it reads the repository and brings the diagram up to date, and the runtime-rendered page follows within minutes. There is no watcher in that sentence on purpose, nothing detects your code changes for you; a merge hook or a human kicks off the agent, whose API key comes with the paid plans.

One source of truth serving every surface, docs page included, is the architecture worth aiming at: see single source of truth for architecture.

What a no-build site cannot promise

The embed URLs exist only for projects shared public; flipping the project private turns the image into a 404. Docsify will not warn you: there is no build step, so there is no link checking of any kind, and a dead embed is only discovered by a reader looking at a broken image.

For small flows that belong to one page, docsify-mermaid style plugins keep the source in the same file as the prose, and that is the honest choice at ten nodes. Generated layout struggles past roughly twenty nodes or when zones matter, which is where the embedded form earns its keep. The plain Markdown baseline is covered in embed diagrams in Markdown.

FAQ

How do I resize an image in Docsify?

Use the :size hint in the title position of Markdown image syntax: ':size=800' sets the width and preserves aspect ratio, ':size=1000x625' sets both dimensions. It works with external URLs as well as local files.

Does Docsify support iframes in Markdown?

Yes. Docsify renders HTML embedded in Markdown at runtime, so a pasted iframe displays as written, no plugin needed. Give it a percentage width and a fixed height for a clean fit inside the content column.

Do embedded diagrams update without redeploying a Docsify site?

Yes, twice over. Docsify has no build step, so nothing is frozen at deploy time, and the diagram is fetched from its source URL on each view. Datadef serves that URL with a five minute cache lifetime, so an edited diagram reaches readers within minutes.

Is Docsify bad for SEO if my architecture docs are public?

Docsify renders content in the browser, so crawlers that do not execute JavaScript see little. Public docs needing search visibility usually add prerendering or use a static generator. For internal docs, the most common Docsify use, this tradeoff is irrelevant.

Can I embed a private diagram in Docsify?

No. Live embed URLs only work while the project is shared public; a private project serves 404s. On a Docsify site the workaround is a committed file: export the diagram as a PNG, drop it into the docs folder next to index.html, and reference it with a relative path. It renders like any local asset and stops updating until someone re-exports it.