3.7 KiB
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}}
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.
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.