Insertar y previsualizar

Una sola etiqueta script dibuja documentos de instrucciones en cualquier página web —tu documentación, una wiki, un centro de ayuda o una vista previa de Markdown— tal como los dibuja instruction.md: las reglas como una lista, y los avisos, las herramientas y los ejemplos como tarjetas. Cambias su aspecto con CSS corriente.

Añádelo a una página

Pon esta línea en tu página, en cualquier lugar. Funciona en cualquier sitio y no necesita nada más.

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

Después escribe un documento dentro de un elemento <instruction-md>, o apunta uno a un archivo:

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>

El texto se puede leer sin el script: hasta que se carga (o si está bloqueado), el documento se muestra como texto sin formato. Un elemento que ya existe también puede convertirse en uno: dale data-instruction-md y se dibuja su texto, o data-src para cargar un archivo.

Versiones

render@1.js y render@1.classic.js son siempre la versión 1.x más reciente: las correcciones y los elementos nuevos llegan sin que cambies nada, y nada de lo que funciona deja de funcionar. Como el archivo cambia, cárgalo sin el atributo integrity, como se muestra arriba.

Para fijar una versión exacta, usa su propia dirección, render@1.1.0.classic.js (o render@1.1.0.js), con su integrity. El archivo de una versión no cambia nunca una vez publicado, y carga su propia copia de Mermaid para los diagramas, así que una página fijada se dibuja igual mientras esa versión se siga sirviendo.

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

Todas las versiones, sus archivos y sus valores de integrity figuran en render@1.versions.json. Un navegador comprueba integrity en el script de otro sitio solo cuando ese sitio lo permite (CORS); hasta que instruction.md envíe esas cabeceras para estos archivos, sirve el archivo fijado desde tu propio sitio con el mismo atributo (consulta Seguridad).

Bloques de código en tu Markdown

La mayoría de las herramientas de Markdown convierten un bloque de código en <pre><code class="language-…">. Escribe un documento de instrucciones en un bloque marcado como instruction:

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

y añade data-fences a la etiqueta script. Cada bloque de ese tipo en la página se dibuja como un documento.

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

Encuentra language-instruction, language-instruction-md, lang-instruction y <pre lang="instruction">, con resaltado o sin él.

Vistas previas en vivo

La vista previa de un editor vuelve a dibujar su HTML mientras escribes. Con data-watch, el renderizador dibuja cada bloque que aparece, todas las veces. Solo mira lo que ha cambiado, y un bloque cuyo texto ya ha dibujado antes se repone tal como estaba en lugar de dibujarse de nuevo, así que escribir sigue siendo rápido.

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

Desde tu propio código, lo mismo se hace con instructionMd.enhance(root, options) e 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 y otros renderizadores

Si generas el HTML tú mismo, el plugin para markdown-it (lo que usan la vista previa de VS Code y muchos generadores de sitios) escribe los bloques de instrucciones como elementos. No tiene dependencias y viene en el paquete 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

Para un sitio estático, dibuja cada documento al compilar y la página no necesitará ningún 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 });

Para el HTML que ha generado otro renderizador, enhanceHtml hace lo mismo con una cadena:

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

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

Atributos

En cada elemento <instruction-md> (las descripciones de las tablas de referencia de esta página están en inglés: se generan a partir de la lista del propio renderizador):

AtributoValoresQué hace
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.

En la etiqueta script:

AtributoQué hace
data-fencesDibuja también los bloques de código de instrucciones de la página.
data-watchLos dibuja de nuevo cada vez que la página añade HTML (una vista previa en vivo). Implica data-fences.
data-theme, data-view, data-views, data-chrome, data-toc, data-back-matter, data-allow-imagesEl mismo atributo en cada elemento en que se convierte un bloque de código.

Pruébalo

Edita el documento y el aspecto. El CSS que aparece debajo es lo que pondrías en tu página para obtener lo mismo.

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

Dale estilo

Cada color, fuente y tamaño es un parámetro CSS (una propiedad personalizada, custom property) cuyo nombre empieza por --imd-. Define uno en el elemento o en cualquier cosa que lo rodee, como defines cualquier CSS. Lo que no definas conserva el aspecto propio del renderizador, claro u oscuro.

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

Los colores siguen el sistema del lector (claro u oscuro), salvo que el elemento indique theme="light" o theme="dark". Un color que definas se aplica en ambos; para definirlo solo para el oscuro, ponlo en una media query prefers-color-scheme: dark, o en instruction-md[theme="dark"].

Tipografía

ParámetroValor predeterminadoQué cambia
--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).

Colores

ParámetroValor predeterminadoQué cambia
--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.

Tonos (los colores con los que se dibuja una regla o un aviso)

ParámetroValor predeterminadoQué cambia
--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.

Forma y espacio

ParámetroValor predeterminadoQué cambia
--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).

Partes

Para algo más que colores, da estilo a una parte del dibujo con ::part(), como en instruction-md::part(callout) { … }. Las partes:

ParteQué es
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.

Temas

El renderizador trae tres aspectos ya preparados: paper (cálido, con serifas), github-like y terminal (oscuro, monoespaciado). Cada uno es una hoja de estilos breve con estos parámetros: elige uno en el campo «Partir de» de arriba para verlo, y copia su CSS. En npm son instruction.md/render/themes/paper.css y similares.

Seguridad

  • Un documento no puede ejecutar nada. Su Markdown se dibuja sin HTML en bruto, los enlaces peligrosos se descartan, los formularios nunca se envían, y los dibujos y diagramas se reducen a formas y texto.
  • Las imágenes están desactivadas hasta que añades allow-images: una imagen es una petición al servidor de alguien.
  • Solo carga lo que permites. src lee de tu propio sitio, de instruction.md y del registro, o de los hosts que nombres en allow-origins, y como máximo 1 MiB.
  • Funciona con una Content-Security-Policy estricta. No compila código en tiempo de ejecución, y sus estilos son hojas de estilo construidas dentro del elemento, así que script-src https://instruction.md es todo lo que necesita. Los diagramas cargan Mermaid desde el mismo lugar cuando alguno entra en pantalla.
  • Fija una copia si quieres. Para servir tú mismo el archivo exacto, descarga una versión, render@1.1.0.classic.js (y vendor/mermaid@11.17.2/mermaid.min.js junto a ella, para los diagramas), y su hash, render@1.1.0.classic.js.sri, para un atributo integrity. Los archivos de una versión nunca cambian, así que el hash sigue siendo correcto.

Una página que ya carga módulos desde instruction.md puede usar en su lugar la compilación como módulo, que exporta las mismas funciones:

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