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.
<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:
<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.
<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:
```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.
<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.
<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):
// 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.
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:
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:
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:
| Attribute | Values | What it does |
|---|---|---|
src | URL | Load the document from an address (same origin, instruction.md, the registry, or allow-origins). |
ref | instruction://owner/name@tag | Load a published instruction from the registry. |
registry | URL | The registry ref reads from. Default https://instruction.md/mcp. |
view | rendered | delivered | source | The view it opens in. Default rendered. |
views | comma list | The views the switch offers; with one, no switch is shown. |
theme | light | dark | auto | The colour scheme of the built-in defaults. Default auto (follows the reader's system). |
chrome | full | bare | bare drops the header, the switch and the contents, for a host with its own. |
toc | side | agenda | none | The contents: a rail beside the text when there is room, above it, or none. |
back-matter | on | off | Rules at a glance, guardrails and figures at the end. Default: with the full chrome. |
allow-images | boolean | Show images. Off by default: an image is a request to its server. |
allow-origins | comma list or * | More hosts src may load from. |
max-bytes | number | The largest document src or ref loads. Default 1 MiB. |
heading-offset | number | Shift the document's headings down, when your page owns the h1. |
params | JSON | Values for the document's parameters, in the delivered view. |
inputs | boolean | The document's parameters as inputs above it, to try values. |
base | URL | The address relative links and images resolve against. |
lang | language tag | The 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:
| Attribute | What it does |
|---|---|
data-fences | Draw the page's instruction code fences too. |
data-watch | Draw 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-images | The 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.
/* 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.
/* 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
| Parameter | Default | What it changes |
|---|---|---|
--imd-font | ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif | The document's text: paragraphs, lists, cards and the chrome. |
--imd-font-heading | var(--imd-font) | Headings and the document's title. Defaults to --imd-font. |
--imd-font-mono | ui-monospace, SFMono-Regular, Menlo, Consolas, monospace | Code, parameters, keyboard keys and other monospaced text. |
--imd-font-size | 15px | The base text size; headings and small print scale from it in em/rem steps. |
--imd-line-height | 1.5 | The base line height (prose reads at 1.75 on its own). |
Colours
| Parameter | Default | What it changes |
|---|---|---|
--imd-fg | #09090b · dark #fafafa | The text colour. |
--imd-bg | #ffffff · dark #09090b | The element's background. Set it to transparent to sit on your page's own. |
--imd-surface | #f4f4f5 · dark #18181b | A quiet fill: the view toggle, figures, asides, step numbers. |
--imd-raised | #ffffff · dark #09090b | What sits on a card (badges, chips, cards themselves) and the ground a tone is tinted into. |
--imd-muted | #6b6b74 · dark #a1a1aa | Secondary text: captions, labels, list markers, counts. |
--imd-border | #e4e4e7 · dark #27272a | Every hairline: cards, tables, the rule list, dividers. |
--imd-link | #09090b · dark #fafafa | Links in the text. |
--imd-code-bg | #f4f4f5 · dark #27272a | The background of code blocks and inline code. |
--imd-object | #09090b · dark #fafafa | The icon colour of declared things: tools, MCP servers, skills, agents. |
--imd-chip-bg | #f4f4f5 · dark #27272a | The background of a parameter chip, like ${customer}. |
--imd-chip-fg | #09090b · dark #fafafa | The text of a parameter chip. |
Tones (what a rule or an alert is drawn in)
| Parameter | Default | What it changes |
|---|---|---|
--imd-tone-must | #2563eb · dark #60a5fa | MUST and ALWAYS rules. |
--imd-tone-should | #2563eb · dark #60a5fa | SHOULD rules. |
--imd-tone-may | #15803d · dark #4ade80 | MAY rules, good examples and passing marks. |
--imd-tone-never | #b91c1c · dark #f87171 | NEVER and MUST NOT rules, bad examples, errors. |
--imd-tone-guardrail | #b91c1c · dark #f87171 | Guardrail alerts. |
--imd-tone-note | #2563eb · dark #60a5fa | Note and info alerts. |
--imd-tone-tip | #15803d · dark #4ade80 | Tip alerts. |
--imd-tone-important | #7c3aed · dark #a78bfa | Important alerts. |
--imd-tone-warning | #b45309 · dark #fbbf24 | Warning alerts, SHOULD NOT rules, highlights and items needing attention. |
--imd-tone-caution | #b45309 · dark #fbbf24 | Caution alerts. |
Shape and space
| Parameter | Default | What it changes |
|---|---|---|
--imd-radius | 8px | The corner radius of cards, code blocks, tables and figures. |
--imd-radius-sm | 6px | The corner radius of small controls: badges, buttons, inputs, tiles. |
--imd-space | 1rem | The padding around the document. |
--imd-max-width | 72ch | The 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:
| Part | What it is |
|---|---|
allow | An agent's or tool's list of allowed items (the chips under Allow). |
aside | A :::aside block. |
attrs | The key/value facts of a declaration (a tool's server, a schedule's time…). |
back-matter | The end of the document: every rule at a glance, the guardrails, the figures. |
badge | A badge in the header: signature, version, revoked. |
blocked | The note under a tool or server blocked in the workspace. |
blocked-mark | The Blocked badge on a declaration. |
body | The body of the document, a rule, an alert or a group. |
callout | A rule, an alert, an example or an output shape. |
caption | A media block's caption. |
card | A :::card block. |
cases | A test's or evaluation's list of cases. |
code | A code block (its head, its code and its caption). |
column | One column of :::columns. |
columns | A :::columns block. |
component | A component the host doesn't have, drawn with its fallback. |
condition | A rule's condition badge (if …). |
copy | The copy source button in the source view. |
definition | The definition text of a script, data or configuration block. |
definitions | A definition list. |
delivered | The delivered view: the text an agent receives. |
deny | An agent's or tool's list of denied items. |
details | A :::details disclosure. |
embed | An embedded resource (![[…]]). |
error | The message shown when the document could not be loaded. |
extension | A block from an extension, drawn with its fallback. |
field | One input of a form preview. |
figure | A figure: a drawing, a Mermaid diagram, a workflow graph, media. |
footnote | One footnote. |
footnote-ref | A footnote's number in the text. |
footnotes | The footnotes at the end. |
form | A form preview (nothing is submitted). |
format | An output's format badge. |
glossary | A glossary. |
grid | A :::grid block. |
group | A policy, an instruction or another group of rules. |
header | The header: title, version and signature. |
html-frame | The sandboxed frame an html fence is drawn in. |
image-placeholder | Where an image stands when images are not allowed. |
include | An include, as a card. |
input | One input of the parameter inputs (the inputs attribute). |
inputs | The parameter inputs above the document. |
integration | The Integration or Not approved mark on a declaration. |
label | The label of a rule, alert, example or form field (MUST, Note, Do…). |
math | Math, inline or displayed. |
media | An image, video or audio block. |
media-placeholder | Where media stands when it isn't loaded. |
meta | The header's line of badges. |
object | A declared tool, MCP server, skill, agent or person, as a card. |
occurrence | A schedule's when, in words. |
panel | A context panel. |
param | A parameter, inline or as its declaration card. |
patch | An inheritance patch: replace, extend or remove. |
prose | A run of Markdown prose. |
rails | An agent's list of rails. |
reason | A rule's Because line. |
ref | An output's schema link. |
reference | A typed reference in the text, drawn as a pill. |
refusals | The line that counts the document's errors. |
root | The element's outer box. |
schema | An output's schema line. |
section | A :::section block. |
skills | An agent's list of skills. |
source | The source view. |
step | One step of :::steps. |
steps | A :::steps block. |
tab | One tab's panel. |
table | A data block drawn as a table. |
tabs | A :::tabs block (and an html fence's Rendered and Code). |
target | An include's source address. |
technical | A script, data, configuration, schedule, workflow, test or evaluation, as a card. |
title | The document's title. |
toc | The contents, as an agenda above the text. |
toc-side | The On this page rail beside the text. |
toggle | The rendered / delivered / source switch. |
tools | An agent's list of tools. |
unapproved | The note under a declaration outside the approved integrations. |
unknown | A 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.
srcreads from your own site, instruction.md and the registry, or the hosts you name inallow-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.mdis 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.jsbeside it, for diagrams), and its hash, render@1.1.0.classic.js.sri, for anintegrityattribute. 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:
<script type="module" src="https://instruction.md/render@1.js"></script>