Welcome to Marqdook

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

# main

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/`](stdlib/) on this site), local `view`, and static export. Join in at [GitHub](https://github.com/cflmy/marqdo).

中文文档请看同目录的 [`00-欢迎.mq.md`](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](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. Bind `hi` to a small Python block:

`hi` =
```python
print("hello-from-python")
```

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 Python, then run the bound fence:

**python = > foreign.probe lang="python"**

1. [ok](access(`python`, "ok"))
  **hello = > foreign.run code=`hi`**
  > print text=`hello`
2. *
  > print text="(python3 not found — install Python 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](stdlib/foreign.mq.md) and the full Python walkthrough in [features/19-foreign-view-cells.mq.md](features/19-foreign-view-cells.mq.md).

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

```text
`分析内核` =

| 名称 | 语言 | 说明 |
|------|------|------|
| 分析 | python | shared state |
| 复核 | python | 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](features/20-okf-ekc.mq.md) for the concepts and commands.

Welcome again — enjoy exploring Marqdo.

## greet

When we meet a visitor `who`, we **print text="Welcome, `who`!"** and close with*None*.

## install

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](https://github.com/cflmy/marqdo/releases) |
| From source | `cargo build --release` (needs a local Rust toolchain) |

Official extensions update independently of the CLI:

```text
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`](features/05-extensions.mq.md).