Intégrer et prévisualiser

Une seule balise script affiche des documents d’instruction sur n’importe quelle page web — votre documentation, un wiki, un centre d’aide ou un aperçu Markdown — comme instruction.md les affiche : les règles en liste, les alertes, les outils et les exemples en cartes. Vous en changez l’apparence avec du CSS ordinaire.

L’ajouter à une page

Placez cette ligne dans votre page, n’importe où. Elle fonctionne sur tous les sites et n’a besoin de rien d’autre.

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

Écrivez ensuite un document dans un élément <instruction-md>, ou pointez-en un vers un fichier :

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>

Le texte reste lisible sans le script : tant qu’il n’est pas chargé (ou s’il est bloqué), le document s’affiche en texte brut. Un élément existant peut aussi en devenir un : donnez-lui data-instruction-md et son texte est affiché, ou data-src pour charger un fichier.

Versions

render@1.js et render@1.classic.js sont toujours la version 1.x la plus récente : les corrections et les nouveaux éléments arrivent sans que vous changiez quoi que ce soit, et rien de ce qui fonctionne ne cesse de fonctionner. Comme le fichier change, chargez-le sans attribut integrity, comme ci-dessus.

Pour épingler plutôt une version exacte, utilisez sa propre adresse, render@1.1.0.classic.js (ou render@1.1.0.js), avec son integrity. Le fichier d’une version ne change jamais une fois publié, et il charge sa propre copie de Mermaid pour les diagrammes : une page épinglée s’affiche donc de la même façon aussi longtemps que la version est servie.

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

Chaque version, ses fichiers et leurs valeurs d’intégrité sont listés dans render@1.versions.json. Un navigateur ne vérifie integrity sur le script d’un autre site que si ce site l’autorise (CORS) ; tant que instruction.md n’envoie pas ces en-têtes pour ces fichiers, servez le fichier épinglé depuis votre propre site avec le même attribut (voir Sécurité).

Les blocs de code dans votre Markdown

La plupart des outils Markdown transforment un bloc de code délimité en <pre><code class="language-…">. Écrivez un document d’instruction dans un bloc marqué instruction :

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

et ajoutez data-fences à la balise script. Chaque bloc de ce type sur la page est affiché comme un document.

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

Le script repère language-instruction, language-instruction-md, lang-instruction et <pre lang="instruction">, avec ou sans coloration syntaxique.

Aperçus en direct

L’aperçu d’un éditeur redessine son HTML pendant que vous tapez. Avec data-watch, le moteur de rendu affiche chaque bloc qui apparaît, à chaque fois. Il ne regarde que ce qui a changé, et un bloc dont il a déjà affiché le texte est remis tel qu’il était plutôt que redessiné : la saisie reste donc rapide.

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

Depuis votre propre code, l’équivalent est instructionMd.enhance(root, options) et 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 et les autres moteurs de rendu

Si vous produisez le HTML vous-même, le plugin pour markdown-it (qu’utilisent l’aperçu de VS Code et de nombreux générateurs de sites) écrit les blocs d’instruction sous forme d’éléments. Il n’a aucune dépendance ; il fait partie du paquet instruction.md.

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

Pour un site statique, générez le rendu de chaque document au moment de la construction, et la page n’a plus besoin d’aucun script :

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 });

Pour du HTML produit par un autre moteur de rendu, enhanceHtml fait la même chose sur une chaîne :

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

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

Attributs

Sur chaque élément <instruction-md> (les descriptions des tableaux de référence de cette page sont en anglais : elles proviennent de la liste du moteur de rendu lui-même) :

AttributValeursCe qu’il fait
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.

Sur la balise script :

AttributCe qu’il fait
data-fencesAffiche aussi les blocs de code d’instruction de la page.
data-watchLes affiche de nouveau chaque fois que la page ajoute du HTML (un aperçu en direct). Implique data-fences.
data-theme, data-view, data-views, data-chrome, data-toc, data-back-matter, data-allow-imagesLe même attribut sur chaque élément que devient un bloc de code.

Essayez

Modifiez le document et son apparence. Le CSS en dessous est ce que vous mettriez sur votre page pour obtenir le même résultat.

--- 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 */

Le mettre en forme

Chaque couleur, police et taille est un paramètre CSS (une propriété personnalisée, custom property) dont le nom commence par --imd-. Définissez-en un sur l’élément ou sur n’importe quel élément qui l’entoure, comme n’importe quel CSS. Tout ce que vous ne définissez pas garde l’apparence propre au moteur de rendu, claire ou sombre.

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; }

Les couleurs suivent le système du lecteur (clair ou sombre), sauf si l’élément indique theme="light" ou theme="dark". Une couleur que vous définissez s’applique dans les deux cas ; pour n’en définir une que pour le mode sombre, placez-la dans une requête média prefers-color-scheme: dark, ou sur instruction-md[theme="dark"].

Polices

ParamètreValeur par défautCe qu’il change
--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).

Couleurs

ParamètreValeur par défautCe qu’il change
--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.

Tons (les couleurs dans lesquelles s’affiche une règle ou une note)

ParamètreValeur par défautCe qu’il change
--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.

Forme et espacement

ParamètreValeur par défautCe qu’il change
--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).

Parties

Pour aller au-delà des couleurs, mettez en forme une partie du rendu avec ::part(), par exemple instruction-md::part(callout) { … }. Les parties :

PartieCe que c’est
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.

Thèmes

Trois apparences prêtes à l’emploi sont fournies avec le moteur de rendu : paper (chaleureuse, avec empattement), github-like et terminal (sombre, à chasse fixe). Chacune est une courte feuille de style composée de ces paramètres : choisissez-en une dans le champ « Partir de » ci-dessus pour la voir, et copiez son CSS. Depuis npm, ce sont instruction.md/render/themes/paper.css et les fichiers du même genre.

Sécurité

  • Un document ne peut rien exécuter. Son Markdown est affiché sans HTML brut, les liens dangereux sont supprimés, les formulaires ne sont jamais envoyés, et les dessins et les diagrammes sont réduits à des formes et à du texte.
  • Les images sont désactivées tant que vous n’ajoutez pas allow-images : une image est une requête vers le serveur de quelqu’un.
  • Il ne charge que ce que vous autorisez. src lit depuis votre propre site, instruction.md et le registre, ou les hôtes que vous nommez dans allow-origins, et au plus 1 Mio.
  • Il fonctionne avec une Content-Security-Policy stricte. Il ne compile aucun code à l’exécution, et ses styles sont des feuilles de style construites à l’intérieur de l’élément : script-src https://instruction.md est donc tout ce qu’il lui faut. Les diagrammes chargent Mermaid depuis le même endroit quand l’un d’eux arrive à l’écran.
  • Épinglez une copie si vous le souhaitez. Pour servir vous-même le fichier exact, téléchargez une version, render@1.1.0.classic.js (et vendor/mermaid@11.17.2/mermaid.min.js à côté, pour les diagrammes), ainsi que son empreinte, render@1.1.0.classic.js.sri, pour un attribut integrity. Les fichiers d’une version ne changent jamais : l’empreinte reste donc correcte.

Une page qui charge déjà des modules depuis instruction.md peut utiliser à la place la version module, qui exporte les mêmes fonctions :

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