Embed and preview

One script tag draws instruction documents on any web page — your docs, a wiki, a help centre, or a Markdown preview — the way instruction.md draws them: rules as a list, alerts, tools and examples as cards. You change how it looks with ordinary CSS.

Add it to a page

Put this line in your page, anywhere. It works on any site and needs nothing else.

HTML
<script src="https://instruction.md/render@1.classic.js" defer></script>

Then write a document inside an <instruction-md> element, or point one at a file:

HTML
<script src="https://instruction.md/render@1.classic.js" defer></script>

<!-- written in the page -->
<instruction-md>
---
spec: "1"
title: Support replies
---
MUST: answer in the customer's language.
NEVER: promise a refund before checking the order.
</instruction-md>

<!-- a file on your site, or a published instruction -->
<instruction-md src="/docs/support.md"></instruction-md>
<instruction-md ref="instruction://acme/support-agent@stable"></instruction-md>

The text stays readable without the script: until it loads (or if it is blocked) the document shows as plain text. An existing element can also become one: give it data-instruction-md and its text is drawn, or data-src to load a file.

Versions

render@1.js and render@1.classic.js are always the newest 1.x: fixes and new elements arrive without you changing anything, and nothing that works stops working. Because the file changes, load it without an integrity attribute, as above.

To pin one exact version instead, use its own address, render@1.1.0.classic.js (or render@1.1.0.js), with its integrity. A version's file never changes once it is released, and it loads its own copy of Mermaid for diagrams, so a pinned page draws the same way for as long as the version is served.

HTML
<script src="https://instruction.md/render@1.1.0.classic.js"
  integrity="sha384-9GGdpGQOoKznsAXHv4dOgHHulOE4pObSP5lP311Dxddc8mVc73++6McGEfOxWJXu"
  crossorigin="anonymous" defer></script>

Every version, its files and their integrity are listed in render@1.versions.json. A browser checks integrity on another site's script only when that site allows it (CORS); until instruction.md sends those headers for these files, serve the pinned file from your own site with the same attribute (see Safety).

Code fences in your Markdown

Most Markdown tools turn a fenced block into <pre><code class="language-…">. Write an instruction document in a fence marked instruction:

Markdown
```instruction
---
spec: "1"
title: Support replies
---
MUST: answer in the customer's language.
```

and add data-fences to the script tag. Every such block on the page is drawn as a document.

HTML
<script src="https://instruction.md/render@1.classic.js" data-fences defer></script>

It finds language-instruction, language-instruction-md, lang-instruction and <pre lang="instruction">, highlighted or not.

Live previews

An editor's preview redraws its HTML as you type. With data-watch the renderer draws each fence that appears, every time. It looks only at what changed, and a fence whose text it has drawn before is put back as it was rather than drawn again, so typing stays fast.

HTML
<script src="https://instruction.md/render@1.classic.js" data-watch data-theme="auto" defer></script>

From your own code, the same is instructionMd.enhance(root, options) and instructionMd.watch(root, options):

JavaScript
// draw the fences under one element, now
instructionMd.enhance(document.querySelector("#preview"), { attributes: { theme: "dark" } });

// and again whenever the preview's HTML changes; stop() ends it
const stop = instructionMd.watch(document.querySelector("#preview"));

markdown-it and other renderers

If you build the HTML yourself, the plugin for markdown-it (what VS Code's preview and many site generators use) writes instruction fences as elements. It has no dependencies; it is in the instruction.md package.

JavaScript
import markdownIt from "markdown-it";
import instructionMd from "instruction.md/render/markdown-it";

const md = markdownIt().use(instructionMd, { attributes: { theme: "auto" } });
const html = md.render(readme);
// ```instruction fences are now <instruction-md> elements:
// load render@1.classic.js on the page that shows the HTML to draw them

For a static site, draw each document at build time and the page needs no script at all:

JavaScript
import { renderToString } from "instruction.md/render/ssr";

// drawn at build time, no script on the page (declarative shadow DOM)
markdownIt().use(instructionMd, { render: (text) => renderToString(text).html });

For HTML that another renderer made, enhanceHtml does the same to a string:

JavaScript
import { enhanceHtml } from "instruction.md/render/markdown-it";

// any Markdown renderer's output: its instruction fences become <instruction-md>
const page = enhanceHtml(htmlFromYourRenderer);

Attributes

On each <instruction-md> element:

AttributeValuesWhat it does
srcURLLoad the document from an address (same origin, instruction.md, the registry, or allow-origins).
refinstruction://owner/name@tagLoad a published instruction from the registry.
registryURLThe registry ref reads from. Default https://instruction.md/mcp.
viewrendered | delivered | sourceThe view it opens in. Default rendered.
viewscomma listThe views the switch offers; with one, no switch is shown.
themelight | dark | autoThe colour scheme of the built-in defaults. Default auto (follows the reader's system).
chromefull | barebare drops the header, the switch and the contents, for a host with its own.
tocside | agenda | noneThe contents: a rail beside the text when there is room, above it, or none.
back-matteron | offRules at a glance, guardrails and figures at the end. Default: with the full chrome.
allow-imagesbooleanShow images. Off by default: an image is a request to its server.
allow-originscomma list or *More hosts src may load from.
max-bytesnumberThe largest document src or ref loads. Default 1 MiB.
heading-offsetnumberShift the document's headings down, when your page owns the h1.
paramsJSONValues for the document's parameters, in the delivered view.
inputsbooleanThe document's parameters as inputs above it, to try values.
baseURLThe address relative links and images resolve against.
langlanguage tagThe language of the renderer's own words (Contents, Parameters, a rule's label): fr, uk… Default: the page's own lang, else English. The document's text is never translated.

On the script tag:

AttributeWhat it does
data-fencesDraw the page's instruction code fences too.
data-watchDraw them again whenever the page adds HTML (a live preview). Implies data-fences.
data-theme, data-view, data-views, data-chrome, data-toc, data-back-matter, data-allow-imagesThe same attribute on every element a fence becomes.

Try it

Edit the document and the look. The CSS under it is what you'd put on your page to get the same.

--- spec: "1" title: Support replies --- MUST: answer in the customer's language. SHOULD: keep a reply under 120 words. NEVER: promise a refund before checking the order. MAY: suggest the help centre when it answers the question. > [!TIP] > Edit this text, or change the colours below.
css
/* the renderer's own look: nothing to set */

Style it

Every colour, font and size is a CSS parameter (a custom property) whose name starts with --imd-. Set one on the element or on anything around it, as you set any CSS. Anything you don't set keeps the renderer's own look, light or dark.

CSS
/* on the element, or on any element around it */
.docs instruction-md {
  --imd-font: "Inter", system-ui, sans-serif;
  --imd-fg: #1c1917;
  --imd-tone-must: #7c3aed;
  --imd-radius: 12px;
}
instruction-md::part(header) { display: none; }

The colours follow the reader's system (light or dark) unless the element says theme="light" or theme="dark". A colour you set applies in both; to set one for dark only, put it in a prefers-color-scheme: dark media query, or on instruction-md[theme="dark"].

Type

ParameterDefaultWhat it changes
--imd-fontui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serifThe document's text: paragraphs, lists, cards and the chrome.
--imd-font-headingvar(--imd-font)Headings and the document's title. Defaults to --imd-font.
--imd-font-monoui-monospace, SFMono-Regular, Menlo, Consolas, monospaceCode, parameters, keyboard keys and other monospaced text.
--imd-font-size15pxThe base text size; headings and small print scale from it in em/rem steps.
--imd-line-height1.5The base line height (prose reads at 1.75 on its own).

Colours

ParameterDefaultWhat it changes
--imd-fg#09090b · dark #fafafaThe text colour.
--imd-bg#ffffff · dark #09090bThe element's background. Set it to transparent to sit on your page's own.
--imd-surface#f4f4f5 · dark #18181bA quiet fill: the view toggle, figures, asides, step numbers.
--imd-raised#ffffff · dark #09090bWhat sits on a card (badges, chips, cards themselves) and the ground a tone is tinted into.
--imd-muted#6b6b74 · dark #a1a1aaSecondary text: captions, labels, list markers, counts.
--imd-border#e4e4e7 · dark #27272aEvery hairline: cards, tables, the rule list, dividers.
--imd-link#09090b · dark #fafafaLinks in the text.
--imd-code-bg#f4f4f5 · dark #27272aThe background of code blocks and inline code.
--imd-object#09090b · dark #fafafaThe icon colour of declared things: tools, MCP servers, skills, agents.
--imd-chip-bg#f4f4f5 · dark #27272aThe background of a parameter chip, like ${customer}.
--imd-chip-fg#09090b · dark #fafafaThe text of a parameter chip.

Tones (what a rule or an alert is drawn in)

ParameterDefaultWhat it changes
--imd-tone-must#2563eb · dark #60a5faMUST and ALWAYS rules.
--imd-tone-should#2563eb · dark #60a5faSHOULD rules.
--imd-tone-may#15803d · dark #4ade80MAY rules, good examples and passing marks.
--imd-tone-never#b91c1c · dark #f87171NEVER and MUST NOT rules, bad examples, errors.
--imd-tone-guardrail#b91c1c · dark #f87171Guardrail alerts.
--imd-tone-note#2563eb · dark #60a5faNote and info alerts.
--imd-tone-tip#15803d · dark #4ade80Tip alerts.
--imd-tone-important#7c3aed · dark #a78bfaImportant alerts.
--imd-tone-warning#b45309 · dark #fbbf24Warning alerts, SHOULD NOT rules, highlights and items needing attention.
--imd-tone-caution#b45309 · dark #fbbf24Caution alerts.

Shape and space

ParameterDefaultWhat it changes
--imd-radius8pxThe corner radius of cards, code blocks, tables and figures.
--imd-radius-sm6pxThe corner radius of small controls: badges, buttons, inputs, tiles.
--imd-space1remThe padding around the document.
--imd-max-width72chThe widest the text column grows (a contents rail is added beside it when there is room).

Parts

For more than colours, style a part of the drawing with ::part(), as in instruction-md::part(callout) { … }. The parts:

PartWhat it is
allowAn agent's or tool's list of allowed items (the chips under Allow).
asideA :::aside block.
attrsThe key/value facts of a declaration (a tool's server, a schedule's time…).
back-matterThe end of the document: every rule at a glance, the guardrails, the figures.
badgeA badge in the header: signature, version, revoked.
blockedThe note under a tool or server blocked in the workspace.
blocked-markThe Blocked badge on a declaration.
bodyThe body of the document, a rule, an alert or a group.
calloutA rule, an alert, an example or an output shape.
captionA media block's caption.
cardA :::card block.
casesA test's or evaluation's list of cases.
codeA code block (its head, its code and its caption).
columnOne column of :::columns.
columnsA :::columns block.
componentA component the host doesn't have, drawn with its fallback.
conditionA rule's condition badge (if …).
copyThe copy source button in the source view.
definitionThe definition text of a script, data or configuration block.
definitionsA definition list.
deliveredThe delivered view: the text an agent receives.
denyAn agent's or tool's list of denied items.
detailsA :::details disclosure.
embedAn embedded resource (![[…]]).
errorThe message shown when the document could not be loaded.
extensionA block from an extension, drawn with its fallback.
fieldOne input of a form preview.
figureA figure: a drawing, a Mermaid diagram, a workflow graph, media.
footnoteOne footnote.
footnote-refA footnote's number in the text.
footnotesThe footnotes at the end.
formA form preview (nothing is submitted).
formatAn output's format badge.
glossaryA glossary.
gridA :::grid block.
groupA policy, an instruction or another group of rules.
headerThe header: title, version and signature.
html-frameThe sandboxed frame an html fence is drawn in.
image-placeholderWhere an image stands when images are not allowed.
includeAn include, as a card.
inputOne input of the parameter inputs (the inputs attribute).
inputsThe parameter inputs above the document.
integrationThe Integration or Not approved mark on a declaration.
labelThe label of a rule, alert, example or form field (MUST, Note, Do…).
mathMath, inline or displayed.
mediaAn image, video or audio block.
media-placeholderWhere media stands when it isn't loaded.
metaThe header's line of badges.
objectA declared tool, MCP server, skill, agent or person, as a card.
occurrenceA schedule's when, in words.
panelA context panel.
paramA parameter, inline or as its declaration card.
patchAn inheritance patch: replace, extend or remove.
proseA run of Markdown prose.
railsAn agent's list of rails.
reasonA rule's Because line.
refAn output's schema link.
referenceA typed reference in the text, drawn as a pill.
refusalsThe line that counts the document's errors.
rootThe element's outer box.
schemaAn output's schema line.
sectionA :::section block.
skillsAn agent's list of skills.
sourceThe source view.
stepOne step of :::steps.
stepsA :::steps block.
tabOne tab's panel.
tableA data block drawn as a table.
tabsA :::tabs block (and an html fence's Rendered and Code).
targetAn include's source address.
technicalA script, data, configuration, schedule, workflow, test or evaluation, as a card.
titleThe document's title.
tocThe contents, as an agenda above the text.
toc-sideThe On this page rail beside the text.
toggleThe rendered / delivered / source switch.
toolsAn agent's list of tools.
unapprovedThe note under a declaration outside the approved integrations.
unknownA block of a kind the specification doesn't have, kept as written.

Themes

Three ready-made looks come with the renderer: paper (warm, serif), github-like and terminal (dark, monospace). Each is a short stylesheet of these parameters: pick one in the playground's Start from to see it, and copy its CSS. From npm they are instruction.md/render/themes/paper.css and the like.

Safety

  • A document can't run anything. Its Markdown is drawn without raw HTML, dangerous links are dropped, forms never submit, and drawings and diagrams are reduced to shapes and text.
  • Images are off until you add allow-images: an image is a request to someone's server.
  • It loads only what you allow. src reads from your own site, instruction.md and the registry, or the hosts you name in allow-origins, and at most 1 MiB.
  • It works under a strict Content-Security-Policy. It compiles no code at run time, and its styles are constructed stylesheets inside the element, so script-src https://instruction.md is all it needs. Diagrams load Mermaid from the same place when one scrolls into view.
  • Pin a copy if you want one. To serve the exact file yourself, download a version, render@1.1.0.classic.js (and vendor/mermaid@11.17.2/mermaid.min.js beside it, for diagrams), and its hash, render@1.1.0.classic.js.sri, for an integrity attribute. A version's files never change, so the hash stays right.

A page that already loads modules from instruction.md can use the module build instead, which exports the same functions:

HTML
<script type="module" src="https://instruction.md/render@1.js"></script>