261 lines
12 KiB
Markdown
261 lines
12 KiB
Markdown
---
|
|
markup: occlusion
|
|
title: ext/web
|
|
description: Executable web handbook: decompose layout down to Markdown leaves.
|
|
import:
|
|
layout: ext/web/layout/index.mq.md
|
|
web: ext/web/web.mq.md
|
|
---
|
|
|
|
Web handbook — split page structure first, author content second, then preview,
|
|
serve and verify. Ordinary .mq.md functions are the tools; no separate Skill
|
|
compiler or manifest is needed. Install with marqdo ext add web. In this source
|
|
repo build with bash scripts/build-web-plugin.sh and optionally select its
|
|
absolute path with MARQDO_WEB_PLUGIN. Keep installation outside source ext.
|
|
|
|
Start with executable evidence
|
|
|
|
Run these from the repository root; installed users replace FILE with its actual
|
|
installed path. Preserve the inner text quotes and protect dollar references
|
|
from shell expansion. Inspect process status and ok before consuming result.
|
|
|
|
```sh
|
|
marqdo call ext/web/index.mq.md layout_rules --json
|
|
marqdo call ext/web/index.mq.md preview_markdown 'body="# Readable page"' 'title="Preview"' --effects plugin --json
|
|
marqdo call ext/web/index.mq.md preview_nodes 'nodes=[{"type":"row","value":[{"type":"markdown","value":"## Left"},{"type":"markdown","value":"## Right"}]}]' --effects plugin --json
|
|
```
|
|
|
|
The engineering method: recursively decompose to Markdown leaves
|
|
|
|
Split home into navigation, main and footer. Split a two-region footer into
|
|
brand and links. If links still contains two columns, split it again into docs
|
|
and community. Continue while a block needs independent internal layout. Stop
|
|
at one simple Markdown responsibility, not at one file per paragraph.
|
|
|
|
```text
|
|
site/
|
|
index.mq.md Document selects the layout root
|
|
components/index.mq.md stack navigation, main, footer
|
|
nav/index.mq.md
|
|
nav/content.md ordinary Markdown links
|
|
main/index.mq.md
|
|
main/content.md ordinary Markdown prose
|
|
footer/index.mq.md columns: brand, links
|
|
brand/index.mq.md
|
|
brand/content.md brand and copyright
|
|
links/index.mq.md columns: docs, community
|
|
docs/index.mq.md
|
|
docs/content.md
|
|
community/index.mq.md
|
|
community/content.md
|
|
pages/about.mq.md another declared page
|
|
api/ping.mq.md Endpoint
|
|
preview.mq.md assemble and render offline
|
|
serve.mq.md process launcher, no page content
|
|
```
|
|
|
|
A parent index imports children, combines their rows and declares one layout
|
|
relationship. A terminal content.md is plain Markdown. Split again if a parent
|
|
contains long content, multiple layout responsibilities or HTML tags. A leaf
|
|
does not decide its external placement. Cutting a large HTML string into files
|
|
still hides the structure in strings. Forms, data sources and interaction need
|
|
their own responsibilities; they do not justify restoring an HTML page shell.
|
|
|
|
Follow the real project
|
|
|
|
The [English reference](../../examples/web-layout-handbook/index.mq.md) implements
|
|
this tree. Follow its [component root](../../examples/web-layout-handbook/components/index.mq.md)
|
|
to footer grandchildren. The [Chinese reference](../../examples/web-layout-handbook-zh/index.mq.md)
|
|
uses the same representation and renderer. Preview from the repo root, then
|
|
change into the site directory to start the process:
|
|
|
|
```text
|
|
marqdo call examples/web-layout-handbook/preview.mq.md main --effects plugin,fs.read,output.write --fs-root examples/web-layout-handbook --json
|
|
marqdo call ext/web/web.mq.md serve 'root="examples/web-layout-handbook"' --effects plugin,fs.read,network.write --fs-root examples/web-layout-handbook --json
|
|
```
|
|
|
|
Check /, /about and /api/ping. The first is a genuinely nested layout, the second
|
|
an ordinary Document, and the third JSON. Wide layouts show columns; narrow
|
|
layouts collapse without authored HTML or CSS.
|
|
|
|
One View representation for both parents and leaves
|
|
|
|
Public columns remain type, slot, value, attrs, style, with Chinese aliases
|
|
类型、槽、值、属性、样式. Use @ record tables for lists of node maps. A row/column
|
|
container holds child rows in value. nav/header/footer/section/aside supply
|
|
semantic regions. A markdown value is content text. Merging defines sibling
|
|
order, not geometry: use columns to establish side-by-side placement. A style
|
|
cell references class names; it neither defines CSS nor silently compiles a theme.
|
|
Runtime defaults supply the basic responsive geometry.
|
|
|
|
Short leaves can pass Markdown directly; longer leaves read a content.md as in
|
|
the reference. Parents retain structural values rather than rendering children
|
|
before composition. This small executable program demonstrates the relationship;
|
|
real sites put each responsibility into the files shown above.
|
|
|
|
```marqdo
|
|
---
|
|
markup: occlusion
|
|
import:
|
|
component: ext/web/component/index.mq.md
|
|
layout: ext/web/layout/index.mq.md
|
|
web: ext/web/web.mq.md
|
|
---
|
|
|
|
# main
|
|
|
|
**left = component.markdown text="### Brand" slot="brand"**
|
|
**right = component.markdown text="[About](/about)" slot="links"**
|
|
**siblings = component.merge a=`left` b=`right`**
|
|
**footer = layout.columns children=`siblings` slot="footer"**
|
|
**html = web.render nodes=`footer` title="Column preview"**
|
|
> print text=`html`
|
|
```
|
|
|
|
Document, Endpoint and lifecycle boundaries
|
|
|
|
Ordinary Documents declare type: web, route and title around Markdown body,
|
|
retaining the existing Markdown/data-source path. A composed Document also
|
|
declares view: main: its ordinary main function returns View rows. serve executes that assembly
|
|
once at startup and uses the same renderer as offline preview. Restart after
|
|
content changes. Automatic data_source binding uses ordinary Documents and
|
|
cannot be mixed with startup assembly. Assembly returns structure; it must not render again or launch
|
|
a server. Request-time interaction belongs in Endpoints with type, path, method,
|
|
request and response metadata. Startup assembly is not an automatic request-time
|
|
template/data-binding system.
|
|
|
|
serve is a blocking lifecycle operation callable with marqdo call. Grant
|
|
plugin,fs.read,network.write for a site that reads Markdown and listens. For
|
|
additional resources, compose web.prepare, resource-owned bindings and
|
|
web.listen in an ordinary callable launcher. Keep each returned app value.
|
|
For current database rows, forms and session-aware navigation, place the typed resources from
|
|
ext/data and component.navigation inside the same View tree. Pure document_head resources
|
|
preserve SEO and font links in previews as well as responses; they never become body content.
|
|
See [the request-resource design](../../doc/design/web-view-resources.md) and the real
|
|
[network site](../../examples/web-net-site/index.mq.md).
|
|
The network library owns WebSocket routes; the security library owns login
|
|
and session policy. Preparing a site opens no listener.
|
|
inspect with root scans disk declarations without listening; an empty app in a
|
|
fresh process cannot inspect another process's private state.
|
|
|
|
```sh
|
|
marqdo call ext/web/web.mq.md inspect 'root="examples/web-layout-handbook"' --effects plugin --json
|
|
```
|
|
|
|
Open the module for the next responsibility
|
|
|
|
[layout](layout/index.mq.md) supplies decomposition, stack and columns;
|
|
[component](component/index.mq.md) supplies Markdown leaves and semantic wrappers;
|
|
[page](page/index.mq.md) supplies handles and offline render;
|
|
[route](route/index.mq.md) is for explicit advanced registration, while whole
|
|
sites normally use Metadata. [dom](dom/index.mq.md) converts content, retaining
|
|
raw HTML only at a compatibility boundary. [head](head.mq.md) contributes pure SEO/font/resource declarations to the real document head;
|
|
[client](client/index.mq.md) loads
|
|
the official Marqdo WASM bridge; business effects stay in lib/browser.
|
|
[_capability](_capability/index.mq.md) diagnoses loading. The [facade](web.mq.md)
|
|
keeps serve/render/inspect and the app API. Data, auth and HTTP clients belong
|
|
to ext/data, ext/security and ext/net. [Chinese handbook](网页/索引.mq.md).
|
|
|
|
Develop and accept a change
|
|
|
|
Compose Markdown, stack and columns before inventing a primitive. Only genuinely
|
|
new structural capability needs plugins/web/internal/artifact and ABI changes;
|
|
ordinary pages need no new host primitive. Keep bilingual helpers and the five
|
|
columns aligned. Put parameter contracts after headings and return contracts
|
|
before execution. ## is a callable heading, not ordinary document sectioning.
|
|
Update src/ext_cli.rs if adding package files. Preserve ordinary Documents and
|
|
Endpoints when changing startup assembly.
|
|
|
|
```text
|
|
marqdo call skills/marqdo-dev/index.mq.md test 'targets=["web_handbook"]' --effects plugin,process.exec --require-ok --json
|
|
marqdo call skills/marqdo-dev/index.mq.md test 'targets=["call_cli","gold"]' 'filter="web"' --effects plugin,process.exec --require-ok --json
|
|
```
|
|
|
|
Handbook tests execute the bilingual sh fences and author examples directly,
|
|
then preview and serve the real reference tree to check structure, routes and
|
|
API behavior. Narration ratio is a minimum, not proof of usability. A checklist
|
|
cannot truthfully accept a component without inspecting its implementation.
|
|
This package does not automatically decompose arbitrary pages or implement a
|
|
full CSS compiler through the style cell; explicit design remains the author's
|
|
responsibility, made followable and testable by these indexes.
|
|
|
|
## site_playbook
|
|
|
|
| 返回 | 类型 | 说明 |
|
|
|------|------|------|
|
|
| result | any | Development workflow and stopping rule |
|
|
|
|
Return the workflow and stopping rule without creating files or claiming to
|
|
accept a particular site. Define the region tree, author parents and Markdown
|
|
leaves, then start and test the declared HTTP surface.
|
|
|
|
The returned rows are a planning aid, not a generated site or a validation certificate. Start with the component tree, give each parent one placement decision, then write the leaves as ordinary Markdown. Declare request-time handlers separately from startup assembly. Preview the composed result before starting the server, and compare real routes and narrow-screen geometry against that same source tree.
|
|
|
|
`workflow` =
|
|
|
|
| key | value |
|
|
|-----|-------|
|
|
| goal | build a site as executable documents |
|
|
| step_A | draw region tree before content |
|
|
| step_B | recursively split components to Markdown leaves |
|
|
| step_C | declare home Document and view main for composed structure |
|
|
| step_D | declare more Documents with their own routes |
|
|
| step_E | declare Endpoint handlers for request-time work |
|
|
| step_F | call the blocking serve function with explicit site root and effects |
|
|
| step_G | compare preview and live output; test routes and browser geometry |
|
|
| stopping_rule | one Markdown responsibility and no internal layout |
|
|
|
|
Return *workflow*.
|
|
|
|
## layout_rules
|
|
|
|
| 返回 | 类型 | 说明 |
|
|
|------|------|------|
|
|
| result | any | Development workflow and stopping rule |
|
|
|
|
Reuse the layout module convention without a second rule catalog. No
|
|
parameters or plugin. Actual acceptance still inspects leaf responsibilities,
|
|
parent relationships and the running result.
|
|
|
|
Return *[Rules](layout.rules())*.
|
|
|
|
## preview_markdown
|
|
|
|
| 参数 | 类型 | 默认 | 说明 |
|
|
|---|---|---|---|
|
|
| body | text | "" | Markdown content |
|
|
| title | text | "Preview" | Document title |
|
|
|
|
| 返回 | 类型 | 说明 |
|
|
|------|------|------|
|
|
| result | text | HTML document |
|
|
|
|
Use `body`="", `title`="Preview" as the inputs for this operation.
|
|
|
|
Render Markdown `body`="" with default `title`="Preview" .
|
|
Return HTML text without writing files or registering routes. For a complex
|
|
page split the layout first; raw HTML strings are not the content strategy.
|
|
This tool needs the native plugin.
|
|
|
|
Return *[Render](web.render(body=`body`, title=`title`))*.
|
|
|
|
## preview_nodes
|
|
|
|
| 参数 | 类型 | 默认 | 说明 |
|
|
|---|---|---|---|
|
|
| nodes | list | required | Nested View rows |
|
|
| title | text | "Preview" | Document title |
|
|
|
|
| 返回 | 类型 | 说明 |
|
|
|------|------|------|
|
|
| result | text | HTML document |
|
|
|
|
Use `nodes`, `title`="Preview" as the inputs for this operation.
|
|
|
|
Render decomposed `nodes` with default `title`="Preview" .
|
|
Parent values retain child rows, while leaf values hold Markdown. Returning
|
|
HTML starts no server. The same renderer serves composed Documents, so this
|
|
preview checks that column relationships survive assembly.
|
|
|
|
Return *[Render](web.render(nodes=`nodes`, title=`title`))*.
|