التضمين والمعاينة
وسم script واحد يعرض مستندات التعليمات على أي صفحة ويب — وثائقك، أو ويكي، أو مركز مساعدة، أو معاينة Markdown — كما يعرضها instruction.md: القواعد في قائمة، والتنبيهات والأدوات والأمثلة في بطاقات. وتغيّر مظهرها بلغة CSS العادية.
إضافته إلى صفحة
ضع هذا السطر في صفحتك، في أي مكان. يعمل على أي موقع ولا يحتاج إلى شيء آخر.
<script src="https://instruction.md/render@1.classic.js" defer></script> ثم اكتب مستندًا داخل عنصر <instruction-md>، أو وجّه عنصرًا إلى ملف:
<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 للمخططات، فتُعرض الصفحة المثبَّتة بالطريقة نفسها ما دام
الإصدار متاحًا.
<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:
```instruction
---
spec: "1"
title: Support replies
---
MUST: answer in the customer's language.
``` وأضف data-fences إلى وسم script. فتُعرض كل كتلة من هذا النوع في الصفحة كمستند.
<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 يعرض العارض كل كتلة تظهر، في كل
مرة. ولا ينظر إلا إلى ما تغيّر، والكتلة التي سبق أن عرض نصها تُعاد كما كانت بدلًا من عرضها من جديد، فتبقى
الكتابة سريعة.
<script src="https://instruction.md/render@1.classic.js" data-watch data-theme="auto" defer></script> ومن الكود الخاص بك، المقابل هو instructionMd.enhance(root, options) و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 والعارضات الأخرى
إذا كنت تبني HTML بنفسك، فإضافة markdown-it
(وهو ما تستخدمه معاينة VS Code وكثير من مولِّدات المواقع) تكتب كتل التعليمات في صورة عناصر. ليست لها أي
تبعيات؛ وهي ضمن حزمة 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 وللموقع الثابت، اعرض كل مستند وقت البناء فلا تحتاج الصفحة إلى أي سكربت:
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 الشيء نفسه على سلسلة نصية:
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> (أوصاف الجداول المرجعية في هذه الصفحة بالإنجليزية: فهي مأخوذة
من قائمة العارض نفسه):
| السمة | القيم | ما تفعله |
|---|---|---|
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. |
على وسم 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 الظاهر تحته هو ما تضعه في صفحتك لتحصل على النتيجة نفسها.
/* the renderer's own look: nothing to set */تنسيقه
كل لون وخط وحجم هو معامل CSS (خاصية مخصَّصة، custom property) يبدأ اسمه بالبادئة --imd-. عيّن أحدها على
العنصر أو على أي شيء يحيط به، كما تعيّن أي 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-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). |
الألوان
| المعامل | القيمة الافتراضية | ما يغيّره |
|---|---|---|
--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. |
الدرجات (الألوان التي تظهر بها قاعدة أو ملاحظة)
| المعامل | القيمة الافتراضية | ما يغيّره |
|---|---|---|
--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. |
الشكل والمسافات
| المعامل | القيمة الافتراضية | ما يغيّره |
|---|---|---|
--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). |
الأجزاء
لما هو أكثر من الألوان، نسّق جزءًا من العرض باستخدام ::part()، كما في
instruction-md::part(callout) { … }. الأجزاء:
| الجزء | ما هو |
|---|---|
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. |
السمات الجاهزة
يأتي مع العارض ثلاثة مظاهر جاهزة: 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 يمكنها أن تستخدم نسخة الوحدة بدلًا من ذلك، وهي تصدّر الدوال نفسها:
<script type="module" src="https://instruction.md/render@1.js"></script>