Files
marqdo/ext/web/dom/index.mq.md

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`))*.