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.
<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 :
<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.
<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 :
```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.
<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.
<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) :
// 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.
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 :
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 :
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) :
| Attribut | Valeurs | Ce qu’il fait |
|---|---|---|
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. |
Sur la balise script :
| Attribut | Ce qu’il fait |
|---|---|
data-fences | Affiche aussi les blocs de code d’instruction de la page. |
data-watch | Les 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-images | Le 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.
/* 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.
/* 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ètre | Valeur par défaut | Ce qu’il change |
|---|---|---|
--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). |
Couleurs
| Paramètre | Valeur par défaut | Ce qu’il change |
|---|---|---|
--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. |
Tons (les couleurs dans lesquelles s’affiche une règle ou une note)
| Paramètre | Valeur par défaut | Ce qu’il change |
|---|---|---|
--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. |
Forme et espacement
| Paramètre | Valeur par défaut | Ce qu’il change |
|---|---|---|
--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). |
Parties
Pour aller au-delà des couleurs, mettez en forme une partie du rendu avec ::part(), par exemple
instruction-md::part(callout) { … }. Les parties :
| Partie | Ce que c’est |
|---|---|
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. |
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.
srclit depuis votre propre site, instruction.md et le registre, ou les hôtes que vous nommez dansallow-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.mdest 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 attributintegrity. 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 :
<script type="module" src="https://instruction.md/render@1.js"></script>