markitect-tool/docs/document-functions.md

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:

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

Fenced block calls use:

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

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

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

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

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

Quoted pipe characters remain literal:

{{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:

mkt function list

Validate calls without rendering:

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

Render deterministic calls:

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:

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.