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.
<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:
<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.
<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:
```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.
<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.
<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):
// 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.
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:
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:
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):
| Atributo | Valores | Qué hace |
|---|---|---|
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. |
En la etiqueta script:
| Atributo | Qué hace |
|---|---|
data-fences | Dibuja también los bloques de código de instrucciones de la página. |
data-watch | Los 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-images | El 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.
/* 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.
/* 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ámetro | Valor predeterminado | Qué cambia |
|---|---|---|
--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). |
Colores
| Parámetro | Valor predeterminado | Qué cambia |
|---|---|---|
--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. |
Tonos (los colores con los que se dibuja una regla o un aviso)
| Parámetro | Valor predeterminado | Qué cambia |
|---|---|---|
--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. |
Forma y espacio
| Parámetro | Valor predeterminado | Qué cambia |
|---|---|---|
--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). |
Partes
Para algo más que colores, da estilo a una parte del dibujo con ::part(), como en
instruction-md::part(callout) { … }. Las partes:
| Parte | Qué es |
|---|---|
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. |
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.
srclee de tu propio sitio, de instruction.md y del registro, o de los hosts que nombres enallow-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.mdes 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.jsjunto a ella, para los diagramas), y su hash, render@1.1.0.classic.js.sri, para un atributointegrity. 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:
<script type="module" src="https://instruction.md/render@1.js"></script>