docs(view): make the writeback page itself the runnable example

Move the foreign + writeback demo into the user persistence page. The page runs a Python code fence, records a keyed total slot, and the slot is visible in both source and static rendering. Remove the separate example document.
This commit is contained in:
cflmy committed 2026-10-18 13:48:05 +08:00
1 parent 5acf026e0c
commit ab6648ae0e
3 files changed
+44 -42

No files matched your search

-34
View File
@@ -1,34 +0,0 @@
---
title: Foreign result writeback
description: Execute a foreign code fence and persist the result into this .mq.md
import foreign:lib/foreign.mq.md
import writeback:lib/writeback.mq.md
---
# main
This is a runnable example, not a screenshot. Run it with:
```text
marqdo run examples/foreign-writeback/index.mq.md
```
The foreign fence below is a normal Marqdo code value. `foreign.run` executes it;
`writeback.record` writes the result into a keyed output slot immediately below
the call. Re-running replaces only the `total` slot.
`合计代码` =
```python
print(950)
```
**结果 = > foreign.run code=`合计代码`**
**> writeback.record value=`结果` key="total"**
<!-- marqdo-out total
950
-->
The keyed slot below is generated by the run:
查看源码,确认 `total` 槽位就在这次 writeback 调用下方。
+22 -4
View File
@@ -1,6 +1,8 @@
---
title: Persisting foreign execution results
description: Static snapshots and writeback — how foreign results survive after the process exits
import foreign:lib/foreign.mq.md
import writeback:lib/writeback.mq.md
---
# main
@@ -9,7 +11,7 @@ Foreign code has two useful lives: as a published snapshot, and as a living docu
---
## Static snapshot: publish the result
Static snapshot: publish the result.
`marqdo view output` executes the document's cells and embeds their real output in the generated HTML. The `.mq.md` source is not modified. This is the default choice for user documentation, reviews and stable links: a reader sees the result without running anything, and the source stays clean.
@@ -17,7 +19,7 @@ The static snapshot is a point-in-time artifact. If an external service changes,
---
## Writeback: keep the result in the source
Writeback: keep the result in the source.
For an exploratory or audit document, pair `foreign` with `lib/writeback`. `writeback.record` writes a keyed output slot next to the call. The slot is visible in the Markdown source, can be reviewed in a diff and can be committed with the document.
@@ -27,12 +29,28 @@ For an exploratory or audit document, pair `foreign` with `lib/writeback`. `writ
| writeback.record | Persist that value in a named slot |
| git diff | Review the changed result like any other document change |
The checked-in runnable example is [examples/foreign-writeback/index.mq.md](https://github.com/cflmy/marqdo/blob/main/examples/foreign-writeback/index.mq.md). Run it with `marqdo run examples/foreign-writeback/index.mq.md`; it writes a `total` slot containing `950` directly below the `writeback.record` call. Re-running replaces only that keyed slot.
A real writeback in this page.
This page is itself the runnable example. The code fence below is ordinary Marqdo data; `foreign.run` executes it, then `writeback.record` writes the `total` slot into this source file.
`写回代码` =
```python
print(950)
```
**结果 = > foreign.run code=`写回代码`**
**> writeback.record value=`结果` key="total"**
<!-- marqdo-out total
950
-->
The generated slot is directly below that call. Re-running the page replaces only the `total` slot; it does not duplicate it.
Writeback is explicit. It is not hidden kernel serialization, does not persist arbitrary kernel memory, and does not touch a file unless the document calls it.
---
## Choosing
Choosing.
For published user docs, use the static snapshot. For a living report that must keep the latest run result in the `.mq.md` itself, use writeback. Both can coexist in one repository: static pages for readers, writeback examples for authors and audits.
+22 -4
View File
@@ -1,6 +1,8 @@
---
title: 外联执行结果的持久化
description: 静态快照与自写回 —— 外联结果在进程退出后如何保留
导入 外联:lib/外联.mq.md
import writeback:lib/writeback.mq.md
---
# main
@@ -9,7 +11,7 @@ description: 静态快照与自写回 —— 外联结果在进程退出后如
---
## 静态快照:发布结果
静态快照:发布结果。
`marqdo view output` 执行文档单元,并把真实输出嵌入生成的 HTML。`.mq.md` 源码不会被修改。这是用户文档、评审和稳定链接的默认选择:读者不需要运行任何东西就能看到结果,源码保持干净。
@@ -17,7 +19,7 @@ description: 静态快照与自写回 —— 外联结果在进程退出后如
---
## 自写回:把结果留在源码里
自写回:把结果留在源码里。
对于探索性或审计型文档,把 `外联` 和 `lib/writeback` 搭配使用。`writeback.record` 会在调用点附近写入带 key 的输出槽位。槽位在 Markdown 源码中可见,可以在 diff 中审阅,也可以随文档提交。
@@ -27,12 +29,28 @@ description: 静态快照与自写回 —— 外联结果在进程退出后如
| writeback.record | 把该值持久化到命名槽位 |
| git diff | 像审阅普通文档改动一样审阅结果 |
可运行示例已经放在仓库里:[examples/foreign-writeback/index.mq.md](https://github.com/cflmy/marqdo/blob/main/examples/foreign-writeback/index.mq.md)。运行 `marqdo run examples/foreign-writeback/index.mq.md`,它会在 `writeback.record` 调用下方写入包含 `950` 的 `total` 槽位。再次运行只替换这个 keyed 槽位。
这一页本身就是完整示例。
这一页就是可运行的示例。下面的代码围栏是普通 Marqdo 值;`外联.运行` 执行它,然后 `writeback.record` 把 `total` 槽位写进本页源码。
`写回代码` =
```python
print(950)
```
**结果 = > 外联.运行 代码=`写回代码`**
**> writeback.record value=`结果` key="total"**
<!-- marqdo-out total
950
-->
生成的槽位就在这次调用下方。再次运行只替换 `total` 槽位,不会重复添加。
自写回是显式动作。它不是隐藏的内核序列化,不持久化任意内核内存,也不会在文档没有调用时修改文件。
---
## 如何选择
如何选择。
面向用户的发布文档用静态快照;需要把最新执行结果留在 `.mq.md` 本身里的活文档用自写回。两者可以共存于同一个仓库:静态页面给读者,自写回示例给作者和审计。