# Document Function Layer

Date: 2026-05-04

## Purpose

Document functions are a Markdown-native authoring surface over existing
Markitect primitives. They let a document author write small deterministic
operations inline or in fenced blocks while preserving diagnostics,
provenance, trace events, capability metadata, and extension descriptors.

The first implementation is intentionally conservative:

- deterministic functions only
- no network access
- no filesystem access
- no external processes
- no provider or assisted-generation calls
- no live flex-auth or external authorization service required

Riskier functions can be added later as optional adapters once capability and
policy gates are explicit.

## Syntax

Inline calls use:

```markdown
{{mkt:text.upper "draft"}}
```

Fenced block calls use:

````markdown
```mkt-function md.codeblock lang=python
print("hello")
```
````

Names are namespace-qualified. Arguments may be positional or named:

```markdown
{{mkt:md.heading text="Decision" level=2}}
```

Pipeline calls pass the previous result as the first argument of the next
function:

```markdown
{{mkt:text.upper "draft" | text.replace DRAFT Final}}
```

Quoted pipe characters remain literal:

```markdown
{{mkt:text.replace "a|b" "|" "/"}}
```

Values of the form `${name}` are resolved from `ProcessingContext.variables`.
This keeps data binding aligned with workflow expression conventions without
creating a second workflow engine.

## Built-In Functions

Initial deterministic functions:

| Function | Purpose |
| --- | --- |
| `text.upper` | Uppercase text. |
| `text.lower` | Lowercase text. |
| `text.title` | Title-case text. |
| `text.trim` | Trim surrounding whitespace. |
| `text.replace` | Replace text. |
| `text.join` | Join values with an optional separator. |
| `md.heading` | Create a Markdown heading. |
| `md.bold` | Create bold Markdown text. |
| `md.link` | Create a Markdown link. |
| `md.codeblock` | Create a fenced code block. |
| `data.get` | Read a value from processing context variables. |

## CLI

List functions:

```text
mkt function list
```

Validate calls without rendering:

```text
mkt function check examples/functions/basic-functions.md
```

Render deterministic calls:

```text
mkt function render examples/functions/basic-functions.md
```

JSON and YAML outputs include calls, diagnostics, provenance, and trace data.

## Registry And Extension Fit

The function layer has its own `DocumentFunctionRegistry`. Functions are
described by `DocumentFunctionDescriptor`:

- stable id and namespace
- parameters
- output type
- execution kind
- capability declarations
- safety metadata
- examples

The built-in extension catalog exposes this layer as `document.function` with
kind `document-function`. This keeps it discoverable without replacing
processors, workflows, references, contracts, templates, or query engines.

## Policy And Capability Gates

The first evaluator blocks non-deterministic functions and supports local
capability blocking through `ProcessingContext.policy`, for example:

```python
ProcessingContext(policy={"blocked_capabilities": ["document_function"]})
```

Future functions that read files, access network resources, invoke external
processes, render exports, or call assisted generation must declare those
capabilities before execution. External policy services may provide decisions
through adapters later, but deterministic function execution has no external
service dependency.

## Natural Extensions

The deterministic layer deliberately stops before becoming a full publishing
language. Future extension work is captured in
`MKTT-WP-0015: Render And Document Function Extensions`.

That workplan should consider:

- typed document values and value-to-Markdown mapping
- richer multiline and nested function syntax
- document-local reusable functions
- render/export adapters, including optional Quarkdown source export
- render-aware numbering, references, tables, figures, equations, and code
  blocks
- static asset and media manifests with checksums
- local permission gates for filesystem, network, external process, assisted,
  and render/export functions

## Design Rules

- Stay close to Markdown and preserve CommonMark documents unless function
  syntax is explicit.
- Keep deterministic execution useful without backends or providers.
- Surface diagnostics instead of silently deleting failed calls.
- Preserve source line information where available.
- Treat functions as an authoring surface over existing capabilities, not as a
  second workflow engine.