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:
1 parent
5acf026e0c
commit
ab6648ae0e
3 files changed
+44
-42
No files matched your search
@@ -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 调用下方。
|
||||
@@ -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.
|
||||
@@ -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` 本身里的活文档用自写回。两者可以共存于同一个仓库:静态页面给读者,自写回示例给作者和审计。
|
||||
Reference in new issue
Block a user