90 lines
3.3 KiB
Markdown
90 lines
3.3 KiB
Markdown
---
|
|
markup: occlusion
|
|
title: ext/web/dom
|
|
description: >-
|
|
DOM Artifact — Markdown/body to structure; raw HTML is escape hatch only
|
|
(ADR 0007). Never use raw as the default homepage method.
|
|
import:
|
|
cap: ext/web/_capability/index.mq.md
|
|
table: lib/table.mq.md
|
|
---
|
|
|
|
DOM helpers separate Markdown content from HTML rendering. Prefer
|
|
[component.markdown](../component/index.mq.md) for layout leaves. from_markdown
|
|
and raw only construct data and need no plugin; render needs --effects plugin.
|
|
|
|
```sh
|
|
marqdo call ext/web/dom/index.mq.md from_markdown 'text="# Readable"' --session handbook --toget body --json
|
|
marqdo call ext/web/dom/index.mq.md render 'dom=$body' --effects plugin --session handbook --json
|
|
```
|
|
|
|
raw remains an explicit compatibility escape hatch, not a homepage layout
|
|
method. Add content behavior through Markdown/render and preserve the existing
|
|
raw path; do not use raw to compensate for missing decomposition.
|
|
|
|
## from_markdown
|
|
|
|
| 参数 | 类型 | 默认 | 说明 |
|
|
|---|---|---|---|
|
|
| text | text | required | Markdown source |
|
|
|
|
| 返回 | 类型 | 说明 |
|
|
|------|------|------|
|
|
| result | any | DOM map |
|
|
|
|
Use `text` as the inputs for this operation.
|
|
|
|
Turn Markdown `text` into a simple DOM map `{kind:"markdown", text}` for
|
|
`page.render` / `web.render`. This is the default body path for Document prose.
|
|
|
|
We retain **`out` = [Set the kind field in the new record](table.put(in=None, at="kind", value="markdown"))**.
|
|
Return *[Set the text field in the new record](table.put(in=`out`, at="text", value=`text`))*.
|
|
|
|
## raw
|
|
|
|
| 参数 | 类型 | 默认 | 说明 |
|
|
|---|---|---|---|
|
|
| html | text | required | raw HTML (escape hatch) |
|
|
|
|
| 返回 | 类型 | 说明 |
|
|
|------|------|------|
|
|
| result | any | DOM map kind=raw |
|
|
|
|
Use `html` as the inputs for this operation.
|
|
|
|
Escape hatch — wrap raw `html`. Prefer Markdown / View nodes. Allowed only when
|
|
table-driven layout cannot express a host constraint; document the why next to
|
|
the call. Forbidden as the primary implementation of nav/sidebar/footer/home.
|
|
|
|
We retain **`out` = [Set the kind field in the new record](table.put(in=None, at="kind", value="raw"))**.
|
|
Return *[Set the html field in the new record](table.put(in=`out`, at="html", value=`html`))*.
|
|
|
|
## render
|
|
|
|
| 参数 | 类型 | 默认 | 说明 |
|
|
|---|---|---|---|
|
|
| dom | any | required | DOM map from from_markdown or raw |
|
|
|
|
| 返回 | 类型 | 说明 |
|
|
|------|------|------|
|
|
| result | any | HTML text |
|
|
|
|
Use `dom` as the inputs for this operation.
|
|
|
|
Render DOM Artifact `dom` (from from_markdown or raw) to HTML via the native
|
|
plugin. When kind is markdown,
|
|
the plugin turns Markdown text into HTML for Document preview. When kind is raw,
|
|
the stored HTML string is returned unchanged — that path exists only for the
|
|
escape hatch documented on raw, not for assembling a full site shell. Prefer
|
|
feeding markdown DOM produced by from_markdown, or skip this helper and use
|
|
page.render / web.render on View tables from file-partitioned components.
|
|
|
|
We **[Load the native plugin required by this operation](cap.load())**.
|
|
We retain **`kind` = [Read kind field](access(`dom`, "kind"))**.
|
|
1. `kind` == "raw"
|
|
We retain **`html` = [Read html field](access(`dom`, "html"))**.
|
|
Return *html*.
|
|
2. *
|
|
We retain **`text` = [Read text field](access(`dom`, "text"))**.
|
|
Return *[Render DOM Artifact dom (from from_markdown or raw) to HTML via the native plugin](web_dom_markdown(text=`text`))*.
|