التضمين والمعاينة

وسم script واحد يعرض مستندات التعليمات على أي صفحة ويب — وثائقك، أو ويكي، أو مركز مساعدة، أو معاينة Markdown — كما يعرضها instruction.md: القواعد في قائمة، والتنبيهات والأدوات والأمثلة في بطاقات. وتغيّر مظهرها بلغة CSS العادية.

إضافته إلى صفحة

ضع هذا السطر في صفحتك، في أي مكان. يعمل على أي موقع ولا يحتاج إلى شيء آخر.

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

ثم اكتب مستندًا داخل عنصر <instruction-md>، أو وجّه عنصرًا إلى ملف:

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>

يبقى النص مقروءًا من دون السكربت: إلى أن يُحمَّل (أو إذا حُظر) يظهر المستند نصًّا عاديًّا. ويمكن لعنصر موجود أن يصير مستندًا أيضًا: أعطه data-instruction-md فيُعرض نصه، أو data-src لتحميل ملف.

الإصدارات

render@1.js وrender@1.classic.js هما دائمًا أحدث إصدار 1.x: تصل الإصلاحات والعناصر الجديدة دون أن تغيّر شيئًا، ولا يتوقف عن العمل شيء كان يعمل. ولأن الملف يتغيّر، حمّله من دون سمة integrity، كما في الأعلى.

ولتثبيت إصدار محدَّد بدلًا من ذلك، استخدم عنوانه الخاص، render@1.1.0.classic.js (أو render@1.1.0.js)، مع سمة integrity الخاصة به. ملف الإصدار لا يتغيّر أبدًا بعد نشره، ويحمّل نسخته الخاصة من Mermaid للمخططات، فتُعرض الصفحة المثبَّتة بالطريقة نفسها ما دام الإصدار متاحًا.

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

كل إصدار وملفاته وقيم integrity الخاصة بها مسرودة في render@1.versions.json. لا يفحص المتصفح integrity في سكربت من موقع آخر إلا إذا سمح ذلك الموقع بذلك (CORS)؛ وإلى أن يرسل instruction.md تلك الترويسات لهذه الملفات، قدّم الملف المثبَّت من موقعك أنت بالسمة نفسها (انظر الأمان).

كتل الكود في ملفات Markdown لديك

معظم أدوات Markdown تحوّل كتلة الكود المسوَّرة إلى <pre><code class="language-…">. اكتب مستند تعليمات في كتلة موسومة بالاسم instruction:

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

وأضف data-fences إلى وسم script. فتُعرض كل كتلة من هذا النوع في الصفحة كمستند.

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

يتعرّف السكربت على language-instruction وlanguage-instruction-md وlang-instruction و<pre lang="instruction">، سواء كانت ملوَّنة أم لا.

المعاينات المباشرة

معاينة المحرر تعيد رسم HTML الخاص بها وأنت تكتب. مع data-watch يعرض العارض كل كتلة تظهر، في كل مرة. ولا ينظر إلا إلى ما تغيّر، والكتلة التي سبق أن عرض نصها تُعاد كما كانت بدلًا من عرضها من جديد، فتبقى الكتابة سريعة.

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

ومن الكود الخاص بك، المقابل هو instructionMd.enhance(root, options) و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 والعارضات الأخرى

إذا كنت تبني HTML بنفسك، فإضافة markdown-it (وهو ما تستخدمه معاينة VS Code وكثير من مولِّدات المواقع) تكتب كتل التعليمات في صورة عناصر. ليست لها أي تبعيات؛ وهي ضمن حزمة 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

وللموقع الثابت، اعرض كل مستند وقت البناء فلا تحتاج الصفحة إلى أي سكربت:

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

ولملفات HTML التي أنتجها عارض آخر، تفعل enhanceHtml الشيء نفسه على سلسلة نصية:

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

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

السمات

على كل عنصر <instruction-md> (أوصاف الجداول المرجعية في هذه الصفحة بالإنجليزية: فهي مأخوذة من قائمة العارض نفسه):

السمةالقيمما تفعله
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.

على وسم script:

السمةما تفعله
data-fencesتعرض أيضًا كتل كود التعليمات في الصفحة.
data-watchتعرضها من جديد كلما أضافت الصفحة HTML (معاينة مباشرة). وتتضمن data-fences.
data-theme، data-view، data-views، data-chrome، data-toc، data-back-matter، data-allow-imagesالسمة نفسها على كل عنصر تصير إليه كتلة كود.

جرّبه

عدّل المستند ومظهره. كود CSS الظاهر تحته هو ما تضعه في صفحتك لتحصل على النتيجة نفسها.

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

تنسيقه

كل لون وخط وحجم هو معامل CSS (خاصية مخصَّصة، custom property) يبدأ اسمه بالبادئة --imd-. عيّن أحدها على العنصر أو على أي شيء يحيط به، كما تعيّن أي CSS. وكل ما لا تعيّنه يحتفظ بمظهر العارض نفسه، فاتحًا كان أم داكنًا.

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

تتبع الألوان نظام القارئ (فاتح أو داكن) ما لم يحدّد العنصر theme="light" أو theme="dark". اللون الذي تعيّنه يسري في الحالتين؛ ولتعيين لون للوضع الداكن فقط، ضعه في استعلام الوسائط prefers-color-scheme: dark، أو على instruction-md[theme="dark"].

الخطوط

المعاملالقيمة الافتراضيةما يغيّره
--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).

الألوان

المعاملالقيمة الافتراضيةما يغيّره
--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.

الدرجات (الألوان التي تظهر بها قاعدة أو ملاحظة)

المعاملالقيمة الافتراضيةما يغيّره
--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.

الشكل والمسافات

المعاملالقيمة الافتراضيةما يغيّره
--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).

الأجزاء

لما هو أكثر من الألوان، نسّق جزءًا من العرض باستخدام ::part()، كما في instruction-md::part(callout) { … }. الأجزاء:

الجزءما هو
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.

السمات الجاهزة

يأتي مع العارض ثلاثة مظاهر جاهزة: paper (دافئ، بخط ذي زوائد)، وgithub-like، وterminal (داكن، بخط ثابت العرض). كل منها ورقة أنماط قصيرة من هذه المعاملات: اختر أحدها من حقل «البدء من» في الأعلى لتراه، وانسخ كود CSS الخاص به. ومن npm هي instruction.md/render/themes/paper.css وما يماثله.

الأمان

  • المستند لا يستطيع تشغيل أي شيء. يُعرض Markdown الخاص به دون HTML خام، وتُحذف الروابط الخطرة، ولا تُرسَل النماذج أبدًا، وتُختزل الرسومات والمخططات إلى أشكال ونص.
  • الصور متوقفة إلى أن تضيف allow-images: فالصورة طلب إلى خادم جهة ما.
  • لا يحمّل إلا ما تسمح به. السمة src تقرأ من موقعك أنت، ومن instruction.md والسجل، أو من الخوادم التي تسمّيها في allow-origins، وبحد أقصى 1 MiB.
  • يعمل مع سياسة Content-Security-Policy صارمة. لا يترجم أي كود وقت التشغيل، وأنماطه أوراق أنماط مبنية داخل العنصر، فكل ما يحتاج إليه هو script-src https://instruction.md. وتحمّل المخططات Mermaid من المكان نفسه عندما يظهر أحدها على الشاشة بالتمرير.
  • ثبّت نسخة إذا أردت. لتقديم الملف نفسه بنفسك، نزّل إصدارًا، render@1.1.0.classic.js (ومعه vendor/mermaid@11.17.2/mermaid.min.js إلى جانبه، للمخططات)، وقيمة التجزئة الخاصة به، render@1.1.0.classic.js.sri، لسمة integrity. ملفات الإصدار لا تتغيّر أبدًا، فتبقى قيمة التجزئة صحيحة.

الصفحة التي تحمّل أصلًا وحدات (modules) من instruction.md يمكنها أن تستخدم نسخة الوحدة بدلًا من ذلك، وهي تصدّر الدوال نفسها:

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