Files
marqdo/public/00-welcome.mq.md
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00

5.9 KiB
Executable File
Raw Permalink Blame History

markup, title, description, import
markup title description import
occlusion Welcome to Marqdo User-docs home — code as documentation (English)
math foreign
lib/math.mq.md lib/foreign.mq.md

main

返回 类型 说明
result any None; execute this page's documented steps in order and observe their output or stated effects

Hello — and welcome. I built Marqdo so that code is documentation and documentation is code: Markdown markers are the program structure, so what you read is what runs.

AI systems already favor Markdown-shaped output. That raised a simple question: why keep docs and programs as two separate artifacts? Marqdo is the answer. The .mq.md suffix exists so a file stays renderable as Markdown while remaining executable. Richer OKF-style YAML catalogs and even slide decks are on the roadmap; for now this site itself is generated by Marqdo — and that often saves tokens when an AI is writing with you.

The language is still early: structural markers, English/Chinese builtin aliases (print / 打印 …), an importable standard library (see stdlib/ on this site), local view, and static export. Join in at GitHub.

中文文档请看同目录的 00-欢迎.mq.md(叙述与内置均用中文)。

Want a quick hello? marqdo run executes the entry # main. Try greet who="marqdo". Names can include spaces: greet who="marqdo user".

This version also runs one function on its own. marqdo call takes the file, the function and named arguments. The page you read is the program that runs. What that is for, and why it matters, is in features/22-call.mq.md.

Beyond the basics, Marqdo ships table, time, text, files, system, math, foreign, and more. Math and foreign deserve a special mention.

Write a math block and bind it with a TeX comment:


% marqdo: var=f
x^2 - 2

Then plot it: _svg = math.plot formula=f var="x" min=-3 max=3

Foreign lets you embed another language. Use Node Intl for locale-aware currency formatting, a genuine presentation boundary:

hi =

console.log(new Intl.NumberFormat("zh-CN", {style:"currency", currency:"CNY"}).format(950));

Under Markdown this stays easy to read — which is the point: code as documentation, documentation as code.

One file, three surfaces.

Surface What it is
Document ordinary Markdown: prose, tables, links and fenced code
Program the same markers are executable: assignments, calls, returns
Knowledge frontmatter, links and generated catalog entries an agent can query

The static site you are reading is generated from these files, so the examples are not screenshots. Run the same source and you get the same page.

Foreign v2 is a good example. Probe Node, then run the bound fence:

We first node = Check the formatting runtime for the next step.

  1. ok) We first hello = Format the native amount for the next step. We now [Display this step's result](> print text=hello).

We now [Display this step's result](> print text="(node not found — install Node to run this cell)").

The same module also supports JSON calls, parallel fan-out, persistent kernels and an explicit state bridge. See stdlib/foreign.mq.md and the native-first Intl walkthrough in features/19-foreign-view-cells.mq.md.

A view document is still a document. Named kernels and a cell order are ordinary bound tables:

`分析内核` =

| 名称 | 语言 | 说明 |
|------|------|------|
| 分析 | node | shared state |
| 复核 | node | isolated state |

`分析单元` =

| 单元 | 内核 | 说明 |
|------|------|------|
| 准备数据 | 分析 | write |
| 计算指标 | 分析 | read |
| 独立复核 | 复核 | validate |

`会话` = > foreign.session kernels=`分析内核` cells=`分析单元`

marqdo view consumes the foreign-owned 会话 handle and turns it into Run All, Step, per-cell kernels, a journal and a state panel. Without 会话, cells are stateless one-shot runs. There is no separate interactive mode or command; marqdo run still executes the file as one program.

Documentation becomes knowledge when it can be discovered, verified and reused. OKF supplies the portable Markdown + YAML shape; EKC projects the repository into catalog layers L0–L4, a graph and an engineering preflight. The source .mq.md remains the only authority; generated artifacts are marked and rebuildable.

Loop Question
OKF How do people and agents share a readable knowledge page?
EKC What existing capability, decision, constraint or failure should be reused before creating more?
Preflight REUSE → ADAPT → CREATE

Read features/20-okf-ekc.mq.md for the concepts and commands.

Welcome again — enjoy exploring Marqdo.

Installation choices.

Install the interpreter (CLI) in any of these ways:

Way Notes
Ubuntu PPA sudo add-apt-repository ppa:cflmy/marqdo then sudo apt install marqdo
GitHub Releases Prebuilt Windows / Linux packages from releases
From source cargo build --release (needs a local Rust toolchain)

Official extensions update independently of the CLI:

marqdo ext add web
marqdo ext add quantum

ext add tries CDN https://ext.marqdo.com first, then GitHub, then the proxy mirror. See features/05-extensions.mq.md.

greet

参数 类型 默认 说明
who any required Recipient name inserted into the greeting
返回 类型 说明
result any None; this function performs the described effects instead of returning business data

When we meet a visitor who, we print text="Welcome, who!" and close withNone.