diff --git a/CHANGELOG.md b/CHANGELOG.md index 5ca8059..5a09c50 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,9 @@ ## Unreleased +### Added +- **`ext/web` 样式装配(`web_style` / `网页.样式装配`)**: 样式即数据表格 —— GFM 样式表(`|选择器|属性|值|`,可用 `|媒体|` 列分组进 `@media` 块)经 `样式装配` 函数转成 CSS 文本,再拼装成完整主题。替代"整段手写 CSS 字符串"的写法,贯彻 文档即代码。见 [marqdo-blog](examples/marqdo-blog/styles/theme.mq.md)。 + ### Changed - **Frontmatter import syntax**: `import bind:target` / `导入 bind:target` (file `.mq.md` or short name `lib.member`). Removed legacy `> path.mq.md` / `> use` imports. See [module-namespace.md](doc/design/module-namespace.md). diff --git a/examples/marqdo-blog/README.md b/examples/marqdo-blog/README.md new file mode 100644 index 0000000..e0287c6 --- /dev/null +++ b/examples/marqdo-blog/README.md @@ -0,0 +1,50 @@ +# examples/marqdo-blog + +一个用 Marqdo 的 `ext/web` 网络扩展库搭建的博客系统示例:美观大气的现代化主题、 +SQLite 驱动的文章/标签、动态路由、WebSocket 实时终端、以及受会话门禁保护的后台 CRUD。 + +## 运行 + +```bash +cargo build -p marqdo_plugin_web +cargo run -- examples/marqdo-blog/index.mq.md +``` + +打开 http://127.0.0.1:18085/: + +- `/` — 首页:文章卡片网格 + 实时 WebSocket 终端 +- `/post/{slug}` — 动态路由渲染单篇文章(标题/日期/标签/正文) +- `/tags` — 标签归档;`/tag/{slug}` 查看某标签下的文章 +- `/about` — 关于页 +- `/admin` — 会话门禁后台,登录 `admin` / `marqdo`,可增删改文章与标签 +- `/live` — WebSocket 回显端点 +- `/static/*` — 静态资源(`public/` 下的 `live.js`) + +## 设计亮点(文档即代码) + +- **样式即数据表格,装配即函数**(`styles/theme.mq.md`): + 主题不再是一大段手写 CSS 字符串,而是由一张张 GFM 样式表组成 —— + `|选择器|属性|值|` 规则行(同一选择器多行自动合并成一条规则), + 响应式用 `|媒体|选择器|属性|值|` 分组进 `@media` 块。 + 每个 `## 段`(基础/顶栏/侧栏/主体/卡片/页脚/表单/响应式)导出一张样式表, + `## 全局` 用 `网页.样式装配` 函数把每张表装配成 CSS 文本,再 `text.str_join` 拼成完整样式表, + 最后经 `页面.样式` 注入页面。样式保持可读的数据表格,不写胶水代码。 +- **页面 = 组件装配 + 主体绑定**(`index.mq.md`): + 导航/侧栏/页脚用 `|组件|样式|` 表装配,文章列表用 `|属性|值|` 绑定 SQLite 字段。 +- **动态路由**:`/post/{slug}` 的 `slug` 注入查询条件,`页面.详情` 把首行渲染成文章。 +- **数据模型**(`db/`):`schema.mq.md` 定义 `posts`/`tags`/`post_tags` 三张表, + `seed.mq.md` 提供种子数据,`index.mq.md` 幂等建表 + 灌数据。 + +## 冒烟测试 + +服务器启动后(端口 18085),运行: + +```bash +bash examples/marqdo-blog/smoke.sh +``` + +覆盖:首页/卡片/主题 CSS/媒体查询、静态资源、动态路由详情、标签归档、鉴权门禁、 +登录会话、后台表单、WebSocket 回显。全部通过时输出 `通过 N / N`。 + +可从仓库根目录或本目录运行:相对 `static_dir`(`public`)与相对数据库路径 +(`data/marqdo-blog.db`)都按**入口脚本所在目录**解析,不依赖终端工作目录。 diff --git a/examples/marqdo-blog/components/foot.mq.md b/examples/marqdo-blog/components/foot.mq.md new file mode 100644 index 0000000..590f0d2 --- /dev/null +++ b/examples/marqdo-blog/components/foot.mq.md @@ -0,0 +1,13 @@ +## 页脚 + +站点页脚。放版权与概览链接。 + +`页脚` = + +| 属性 | 值 | 样式 | +|------|-----|------| +| © 2026 Marqdo 博客 | / | | +| 关于 | /about | | +| 后台 | /admin | | + +**`页脚`** \ No newline at end of file diff --git a/examples/marqdo-blog/components/nav.mq.md b/examples/marqdo-blog/components/nav.mq.md new file mode 100644 index 0000000..221c630 --- /dev/null +++ b/examples/marqdo-blog/components/nav.mq.md @@ -0,0 +1,15 @@ +## 导航 + +站点顶部导航。首项是站点名(渐变 Logo 由主题 CSS 处理),`后台` 指向需要登录的 `/admin`。 + +`导航` = + +| 属性 | 值 | 样式 | +|------|-----|------| +| Marqdo 博客 | / | | +| 首页 | / | | +| 标签 | /tags | | +| 关于 | /about | | +| 后台 | /admin | | + +**`导航`** \ No newline at end of file diff --git a/examples/marqdo-blog/components/side.mq.md b/examples/marqdo-blog/components/side.mq.md new file mode 100644 index 0000000..7f83c2f --- /dev/null +++ b/examples/marqdo-blog/components/side.mq.md @@ -0,0 +1,15 @@ +## 侧栏 + +右侧归档面板:文章入口、标签、实时小部件。 + +`侧栏` = + +| 属性 | 值 | 样式 | +|------|-----|------| +| 全部文章 | / | | +| 标签归档 | /tags | | +| 关于本站 | /about | | +| 发布文章 | /admin/new | | +| 实时终端 | /#live | | + +**`侧栏`** \ No newline at end of file diff --git a/examples/marqdo-blog/db/index.mq.md b/examples/marqdo-blog/db/index.mq.md new file mode 100644 index 0000000..77dca7b --- /dev/null +++ b/examples/marqdo-blog/db/index.mq.md @@ -0,0 +1,28 @@ +--- +title: db/index +description: 打开 sqlite、建三张表、幂等种子。 +导入 网页:ext/web/网页.mq.md +import schema:schema.mq.md +import seed:seed.mq.md +--- + +## 打开 + +*store = > 网页.数据库 地址="sqlite:data/marqdo-blog.db"* +*字段 = > schema.posts* +*标签字段 = > schema.tags* +*关联字段 = > schema.post_tags* +> `store`.初始化 名=posts 字段=`字段` +> `store`.初始化 名=tags 字段=`标签字段` +> `store`.初始化 名=post_tags 字段=`关联字段` +*行 = > store.查询 表="posts" 上限=1* +1. `行` + **store** +2. * + *文章 = > seed.posts* + *标签 = > seed.tags* + *关联 = > seed.post_tags* + > `store`.插入 表=posts 行=`文章` + > `store`.插入 表=tags 行=`标签` + > `store`.插入 表=post_tags 行=`关联` + **store** \ No newline at end of file diff --git a/examples/marqdo-blog/db/schema.mq.md b/examples/marqdo-blog/db/schema.mq.md new file mode 100644 index 0000000..a5c9ded --- /dev/null +++ b/examples/marqdo-blog/db/schema.mq.md @@ -0,0 +1,46 @@ +## posts + +文章主表结构。`slug` 用于详情页 `/post/{slug}` 的动态路由;`content` 存 Markdown 正文;`tag` 是主标签(tags 表 slug)。 + +`schema` = + +| 字段 | 类型 | 可空 | +|------|------|------| +| id | integer | false | +| title | text | false | +| slug | text | false | +| summary | text | true | +| content | text | true | +| tag | text | true | +| created_at | text | true | +| updated_at | text | true | + +**`schema`** + +## tags + +标签表结构。 + +`tags` = + +| 字段 | 类型 | 可空 | +|------|------|------| +| id | integer | false | +| name | text | false | +| slug | text | false | + +**`tags`** + +## post_tags + +文章-标签关联表结构。 + +`post_tags` = + +| 字段 | 类型 | 可空 | +|------|------|------| +| id | integer | false | +| post_id | integer | false | +| tag_id | integer | false | + +**`post_tags`** \ No newline at end of file diff --git a/examples/marqdo-blog/db/seed.mq.md b/examples/marqdo-blog/db/seed.mq.md new file mode 100644 index 0000000..4671529 --- /dev/null +++ b/examples/marqdo-blog/db/seed.mq.md @@ -0,0 +1,53 @@ +## posts + +种子文章。首页与详情页的初始数据。created_at 用于按时间倒序展示;tag 是主标签 slug。 + +`posts` = + +| 行 | title | slug | summary | content | tag | created_at | updated_at | +|----|-------|------|---------|---------|-----|------------|------------| +| 1 | 你好,Marqdo 博客 | hello-marqdo | 用 Marqdo 的 web 扩展库搭建的第一个博客。表格即组件、文档即代码。 | 这是一篇介绍博客系统的文章。它由 Marqdo 脚本在启动时写入 SQLite,通过 ext/web 的组件装配渲染成页面。 | marqdo | 2026-08-01 | 2026-08-02 | +| 2 | 动态路由与文章详情 | dynamic-routing | 如何用 /post/{slug} 动态路由渲染单篇文章。 | 本文说明动态路由机制:作者面注册带 {slug} 占位符的路由,请求时把路径参数注入页面查询条件。 | web | 2026-08-05 | 2026-08-05 | +| 3 | 用 GFM 表格表达数据 | gfm-tables | Marqdo 的字典操作不依赖 json 库,GFM 表格即可完成。 | 表格即数据、表格即组件。这篇文章展示如何在 .mq.md 里用横向表写种子数据,用脚注索引读取字段。 | tutorial | 2026-08-10 | 2026-08-11 | +| 4 | WebSocket 实时小部件 | websocket-live | 给博客加一个实时回显的 WebSocket 端点。 | 通过 app.路由实时 注册 /live 端点,配合 public/live.js 在首页显示实时连接状态。 | realtime | 2026-08-15 | 2026-08-15 | +| 5 | 会话与登录鉴权 | session-auth | 后台用 session 门禁保护,只有登录用户能发布文章。 | 用 app.鉴权 配置管理员用户表,/admin 下的 CRUD 页面都需要有效会话。 | web | 2026-08-18 | 2026-08-20 | +| 6 | 数据库与 CRUD | database-crud | 博客的文章、标签、关联全部由 SQLite 支撑。 | db.初始化 建表、db.插入 写种子、后台表单增删改。文章与标签通过 post_tags 关联。 | database | 2026-08-20 | 2026-08-21 | + +**`posts`** + +## tags + +种子标签。 + +`tags` = + +| 行 | name | slug | +|----|------|------| +| 1 | Marqdo | marqdo | +| 2 | Web | web | +| 3 | 教程 | tutorial | +| 4 | 数据库 | database | +| 5 | 实时 | realtime | + +**`tags`** + +## post_tags + +种子文章-标签关联。 + +`post_tags` = + +| 行 | post_id | tag_id | +|----|---------|--------| +| 1 | 1 | 1 | +| 2 | 1 | 2 | +| 3 | 2 | 2 | +| 4 | 3 | 1 | +| 5 | 3 | 3 | +| 6 | 4 | 5 | +| 7 | 4 | 2 | +| 8 | 5 | 2 | +| 9 | 6 | 4 | +| 10 | 6 | 1 | + +**`post_tags`** \ No newline at end of file diff --git a/examples/marqdo-blog/index.mq.md b/examples/marqdo-blog/index.mq.md new file mode 100644 index 0000000..3c465ab --- /dev/null +++ b/examples/marqdo-blog/index.mq.md @@ -0,0 +1,109 @@ +--- +title: Marqdo 博客 +description: 用 web 扩展库搭建的博客系统示例:首页列表、动态文章详情、标签归档、登录门禁后台。 +导入 网页:ext/web/网页.mq.md +import theme:styles/theme.mq.md +import nav:components/nav.mq.md +import side:components/side.mq.md +import foot:components/foot.mq.md +import db:db/index.mq.md +--- + +# main + +`首页` = + +| 组件 | 样式 | +|------|------| +| nav.`导航` | | +| side.`侧栏` | | +| foot.`页脚` | | + +`列表` = + +| 属性 | 值 | 样式 | +|------|-----|------| +| title | posts.title | | +| body | posts.summary | | +| meta | posts.created_at | | +| tag | posts.tag | | +| href | posts.slug | | + +`详情绑定` = + +| 属性 | 值 | 样式 | +|------|-----|------| +| title | posts.title | | +| meta | posts.created_at | | +| tag | posts.tag | | +| body | posts.content | | + +`标签列表` = + +| 属性 | 值 | 样式 | +|------|-----|------| +| title | tags.name | | +| meta | 点击查看该标签下的文章 | | +| href | tags.slug | | + +`文章条件` = + +| 字段 | 操作 | 值 | +|------|------|-----| +| slug | = | {slug} | + +`标签条件` = + +| 字段 | 操作 | 值 | +|------|------|-----| +| tag | = | {slug} | + +`管理员` = + +| 行 | 用户名 | 密码 | +|----|--------|------| +| 1 | admin | marqdo | + +*store = > db.打开* + +*首页CSS = > theme.全局* + +*page = > 网页.页面 标题="Marqdo 博客" 引言="
用 web 扩展库搭建的博客:表格装配页面、SQLite 数据、动态路由、实时终端。
connecting…
"* +*page = > page.组件装配 组件=`首页`* +*page = > page.主体装配 主体=`列表`* +*page = > page.排序 排序="-created_at"* +*page = > page.样式 样式=`首页CSS`* + +*about = > 网页.页面 标题="关于" 引言="一个用 Marqdo 的 web 扩展库(ext/web)写成的博客系统。
它演示了:GFM 表格装配导航与侧栏、SQLite 驱动的主体绑定、动态路由 /post/{slug}、标签归档、以及受 session 保护的后台 CRUD。
"* +*about = > about.组件装配 组件=`首页`* +*about = > about.样式 样式=`首页CSS`* + +*post = > 网页.页面 标题="文章"* +*post = > post.组件装配 组件=`首页`* +*post = > post.主体装配 主体=`详情绑定`* +*post = > post.查询条件 条件=`文章条件`* +*post = > post.详情 详情=True* +*post = > post.样式 样式=`首页CSS`* + +*tags = > 网页.页面 标题="标签归档" 引言="点击标签查看该主题下的文章。
"* +*tags = > tags.组件装配 组件=`首页`* +*tags = > tags.主体装配 主体=`标签列表`* +*tags = > tags.链接前缀 前缀="/tag/"* +*tags = > tags.样式 样式=`首页CSS`* + +*tagged = > 网页.页面 标题="标签"* +*tagged = > tagged.组件装配 组件=`首页`* +*tagged = > tagged.主体装配 主体=`列表`* +*tagged = > tagged.查询条件 条件=`标签条件`* +*tagged = > tagged.排序 排序="-created_at"* +*tagged = > tagged.样式 样式=`首页CSS`* + +*app = > 网页.应用 页面=page 数据库=store 后台=True 主机="127.0.0.1" 端口=18085* +*app = > app.路由 路径="/about" 页面=about* +*app = > app.路由 路径="/post/{slug}" 页面=post* +*app = > app.路由 路径="/tags" 页面=tags* +*app = > app.路由 路径="/tag/{slug}" 页面=tagged* +*app = > app.静态 目录="public" 挂载="/static"* +*app = > app.路由实时 路径="/live" 回显=True* +*app = > app.鉴权 用户表=`管理员` 会话时长=3600* +> `app`.监听 \ No newline at end of file diff --git a/examples/marqdo-blog/public/live.js b/examples/marqdo-blog/public/live.js new file mode 100644 index 0000000..705753a --- /dev/null +++ b/examples/marqdo-blog/public/live.js @@ -0,0 +1,40 @@ +// 实时 WebSocket 小部件(连接 /live 端点)。 +// 连接 ws://host/live,发送输入,展示服务器回显。 +(function () { + var out = document.getElementById("live-out"); + var input = document.getElementById("live-msg"); + var btn = document.getElementById("live-send"); + var status = document.getElementById("live-status"); + if (!out || !input || !btn || !status) return; + + var proto = location.protocol === "https:" ? "wss" : "ws"; + var ws = new WebSocket(proto + "://" + location.host + "/live"); + status.textContent = "connecting…"; + + ws.onopen = function () { + status.textContent = "connected"; + btn.disabled = false; + }; + ws.onmessage = function (ev) { + var p = document.createElement("p"); + p.textContent = "echo: " + ev.data; + out.appendChild(p); + out.scrollTop = out.scrollHeight; + }; + ws.onclose = function () { + status.textContent = "closed"; + btn.disabled = true; + }; + ws.onerror = function () { + status.textContent = "error"; + btn.disabled = true; + }; + + btn.onclick = function () { + var m = input.value.trim(); + if (m) ws.send(m); + }; + input.addEventListener("keydown", function (e) { + if (e.key === "Enter") btn.onclick(); + }); +})(); diff --git a/examples/marqdo-blog/smoke.sh b/examples/marqdo-blog/smoke.sh new file mode 100755 index 0000000..fc20f54 --- /dev/null +++ b/examples/marqdo-blog/smoke.sh @@ -0,0 +1,68 @@ +#!/usr/bin/env bash +# 冒烟测试:marqdo-blog 全功能验证。 +# 用法:bash examples/marqdo-blog/smoke.sh +set -uo pipefail +BASE="http://127.0.0.1:18085" +PASS=0; FAIL=0 +ok() { echo " ok: $1"; PASS=$((PASS+1)); } +bad() { echo " FAIL: $1"; FAIL=$((FAIL+1)); } + +echo "== 首页 ==" +code=$(curl -s -o /dev/null -w "%{http_code}" "$BASE/") +[ "$code" = "200" ] && ok "GET / -> $code" || bad "GET / -> $code" +curl -s "$BASE/" | grep -q '404 not found: {}
", esc(&path))).into_response(); - }; - Html(render::render_page(page, st.db_url.as_deref())).into_response() } fn render_part_from_page(page: &Value, id: &str, db_url: Option<&str>) -> Response { @@ -206,26 +256,6 @@ async fn home_part(State(st): Statebad part path {}
", esc(full))).into_response(); - }; - if page_path.is_empty() || page_path == "/" { - return render_part_from_page(&st.page, &id, st.db_url.as_deref()); - } - let Some(page) = st.routes.get(page_path) else { - return Html(format!("404 not found: {}
", esc(page_path))).into_response(); - }; - render_part_from_page(page, &id, st.db_url.as_deref()) -} - async fn form_get(State(st): Stateunknown form {id}
")).into_response(); diff --git a/plugins/web/src/lib.rs b/plugins/web/src/lib.rs index df061f7..3b2db0d 100644 --- a/plugins/web/src/lib.rs +++ b/plugins/web/src/lib.rs @@ -9,6 +9,8 @@ mod session; mod table; mod ws; +use crate::table::as_css_named; + use std::ffi::{CStr, CString}; use std::os::raw::{c_char, c_int, c_void}; use std::path::PathBuf; @@ -275,6 +277,71 @@ web_ffi!(web_compose_main, |args: &Value| { compose::compose_main(&page, &main, |path| call_lib(path)) }); +web_ffi!(web_page_query, |args: &Value| { + let page = args.get("page").cloned().unwrap_or(json!({})); + let query = args.get("query").cloned().unwrap_or(json!({})); + let mut obj = page.as_object().cloned().unwrap_or_default(); + obj.insert("query".into(), query); + Ok(Value::Object(obj)) +}); + +web_ffi!(web_page_order, |args: &Value| { + let page = args.get("page").cloned().unwrap_or(json!({})); + let order = arg_str(args, "order")?.to_string(); + let mut obj = page.as_object().cloned().unwrap_or_default(); + obj.insert("order".into(), json!(order)); + Ok(Value::Object(obj)) +}); + +web_ffi!(web_page_link_prefix, |args: &Value| { + let page = args.get("page").cloned().unwrap_or(json!({})); + let prefix = arg_str(args, "prefix")?.to_string(); + let mut obj = page.as_object().cloned().unwrap_or_default(); + obj.insert("link_prefix".into(), json!(prefix)); + Ok(Value::Object(obj)) +}); + +web_ffi!(web_page_css, |args: &Value| { + let page = args.get("page").cloned().unwrap_or(json!({})); + let css = arg_str_opt(args, "css").unwrap_or("").to_string(); + let mut obj = page.as_object().cloned().unwrap_or_default(); + if !css.trim().is_empty() { + let prev = obj + .get("styles_css") + .and_then(|v| v.as_str()) + .unwrap_or("") + .to_string(); + obj.insert("styles_css".into(), json!(format!("{prev}\n{css}"))); + } + Ok(Value::Object(obj)) +}); + +// Assemble a GFM style table into CSS text. +// +// Two shapes are accepted: +// 1. Rule rows `|选择器|属性|值|` → `selector { prop: value; }` +// 2. Property rows `|属性|值|` → `.name { prop: value; }` +// +// The `name` argument names the CSS class for shape 2, and is ignored for +// shape 1. This is how Marqdo-side theme modules turn style tables into a +// stylesheet with 文档即代码 — styles are data, assembly is a function. +web_ffi!(web_style, |args: &Value| { + let name = arg_str_opt(args, "name").unwrap_or("").to_string(); + let table = args.get("table").cloned().unwrap_or(json!([])); + Ok(Value::String(as_css_named(&name, &table))) +}); + +web_ffi!(web_page_detail, |args: &Value| { + let page = args.get("page").cloned().unwrap_or(json!({})); + let on = args + .get("detail") + .and_then(|v| v.as_bool()) + .unwrap_or(true); + let mut obj = page.as_object().cloned().unwrap_or_default(); + obj.insert("detail".into(), json!(on)); + Ok(Value::Object(obj)) +}); + web_ffi!(web_compose_form, |args: &Value| { let page = args.get("page").cloned().unwrap_or(json!({})); let form = args @@ -335,7 +402,12 @@ web_ffi!(web_db_select, |args: &Value| { } Some(v) => Some(v), }; - db::select(&url, &table, limit, where_v) + let order = args.get("order").and_then(|v| v.as_str()); + if order.is_some_and(|s| !s.trim().is_empty()) { + db::select_order(&url, &table, limit, where_v, order) + } else { + db::select(&url, &table, limit, where_v) + } }); web_ffi!(web_db_get, |args: &Value| { @@ -893,6 +965,36 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int web_compose_components as PluginFn, ), ("web_compose_main", "page,main", web_compose_main as PluginFn), + ( + "web_page_query", + "page,query", + web_page_query as PluginFn, + ), + ( + "web_page_order", + "page,order", + web_page_order as PluginFn, + ), + ( + "web_page_link_prefix", + "page,prefix", + web_page_link_prefix as PluginFn, + ), + ( + "web_page_css", + "page,css", + web_page_css as PluginFn, + ), + ( + "web_page_detail", + "page,detail", + web_page_detail as PluginFn, + ), + ( + "web_style", + "name,table", + web_style as PluginFn, + ), ( "web_compose_form", "page,form,id", @@ -904,7 +1006,7 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int ("web_db_insert", "url,table,rows", web_db_insert as PluginFn), ( "web_db_select", - "url,table,where,limit", + "url,table,where,limit,order", web_db_select as PluginFn, ), ("web_db_get", "url,table,id", web_db_get as PluginFn), diff --git a/plugins/web/src/render.rs b/plugins/web/src/render.rs index e6c819b..6ce688f 100644 --- a/plugins/web/src/render.rs +++ b/plugins/web/src/render.rs @@ -1,6 +1,6 @@ //! Minimal HTML shell for assembled pages / parts. -use serde_json::{Map, Value}; +use serde_json::{json, Map, Value}; use crate::db; use crate::table::{as_bind, normalize_ref, normalize_slot, parse_site_path, project_rows, SitePath}; @@ -77,9 +77,7 @@ fn resolve_links(raw: Option<&Value>, db_url: Option<&str>) -> Vec<(String, Stri let Some(table) = table else { return Vec::new(); }; - let Ok(data) = db::select(url, &table, 200, None) else { - return Vec::new(); - }; + let data = select_page_data(url, &table, raw, 200); let rows = data .get("rows") .and_then(|v| v.as_array()) @@ -149,9 +147,7 @@ fn resolve_main(args: &Value, db_url: Option<&str>) -> (String, Vec