markitect-tool/workplans/MKTT-WP-0015-render-and-document-function-extensions.md

---
id: MKTT-WP-0015
type: workplan
title: "Render And Document Function Extensions"
domain: markitect
status: todo
owner: markitect-tool
topic_slug: markitect
planning_priority: P2
planning_order: 130
depends_on_workplans:
  - MKTT-WP-0010
  - MKTT-WP-0011
  - MKTT-WP-0012
related_workplans:
  - MKTT-WP-0007
  - MKTT-WP-0008
  - MKTT-WP-0009
  - MKTT-WP-0013
created: "2026-05-04"
updated: "2026-05-04"
state_hub_workstream_id: "a38f676a-0d0b-493c-9792-2e34480c3681"
---

# MKTT-WP-0015: Render And Document Function Extensions

## Purpose

Capture the natural follow-on work from the Quarkdown comparison and the first
Markitect document-function layer.

The current function layer is intentionally small: deterministic functions,
Markdown-native explicit syntax, local context variables, diagnostics,
provenance, and capability metadata. This workplan should extend that model
only when the need is concrete, keeping the core framework clean and avoiding a
second workflow engine.

## Background

Quarkdown shows the value of a document language where functions are not just
macros. They can return typed values, Markdown content, layout structures,
tables, dictionaries, booleans, and renderable nodes. Its compiler expands
function-call nodes, maps output values back to renderable nodes, and then
continues through traversal, rendering, and post-rendering stages.

Markitect should not become a Quarkdown clone. The better fit is:

- keep Markitect as the contract, reference, processor, workflow, cache,
  provenance, and policy framework
- make document functions an authoring surface over those primitives
- add render/export behavior as optional extensions
- use Quarkdown as an optional external publishing target where that is useful

## Decision

Defer this work until after the current original successor work is stable,
unless a concrete document publishing, render provenance, or function-language
use case becomes urgent.

When picked up, treat this as an extension workplan. It may evolve framework
interfaces, but should not make Quarkdown, flex-auth, network access, live LLM
calls, filesystem writes, or external processes required for deterministic
Markitect parsing and function validation.

## P15.1 - Typed document values and value mapping

```task
id: MKTT-WP-0015-T001
status: todo
priority: high
state_hub_task_id: "995945c5-6cec-435c-8943-b8da0a9ff89d"
```

Define a typed value model for document functions:

- string, number, boolean, none
- Markdown content
- list and dictionary values
- references and content units
- tables and records
- diagnostics-friendly unknown or dynamic values

Define how each value maps back to Markdown or structured output. Keep the
mapper deterministic and inspectable.

Output: value model, mapper API, tests, and documentation.

## P15.2 - Richer function syntax without losing Markdown compatibility

```task
id: MKTT-WP-0015-T002
status: todo
priority: medium
state_hub_task_id: "bfce1388-e123-4e91-a5ab-ba67d21c22b8"
```

Evaluate syntax extensions that improve author ergonomics without turning
Markitect into a full compiler language:

- multiline argument continuation
- nested function expressions
- clearer escaping rules
- block-body argument refinements
- source spans beyond line numbers
- cycle and depth limits for nested calls

Output: syntax compatibility note, parser tests, and diagnostics examples.

## P15.3 - Document-local reusable functions

```task
id: MKTT-WP-0015-T003
status: todo
priority: medium
state_hub_task_id: "a8a8f017-3622-47f1-814e-0c71bd49a42f"
```

Explore document-local reusable functions as a constrained, contract-aware
extension:

- named reusable snippets
- parameter lists and default values
- body arguments
- provenance for expansions
- validation against allowed function namespaces

Avoid general-purpose Turing-complete scripting in core. If assisted or
external behavior is needed, route it through workflow steps and explicit
capability gates.

Output: design proposal and one deterministic prototype if justified.

## P15.4 - Quarkdown and render/export adapters

```task
id: MKTT-WP-0015-T004
status: todo
priority: high
state_hub_task_id: "69e550a0-188b-4bc4-9658-47219b090904"
```

Design optional render/export adapters:

- emit Quarkdown source from Markitect references, processors, templates, and
  function calls
- support output profiles such as plain, docs, slides, paged, and static site
- invoke external renderers only through declared capabilities
- keep direct code reuse license-safe
- track source to rendered-artifact provenance

Output: adapter interface, Quarkdown export sketch, policy model, and tests
with deterministic fake renderers.

## P15.5 - Render-aware references, numbering, and assets

```task
id: MKTT-WP-0015-T005
status: todo
priority: high
state_hub_task_id: "53eb9f94-830b-4fdf-bb47-3f549048c82a"
```

Extend the reference model for rendered documents:

- figures, tables, equations, code blocks, and custom numbered units
- generated table of contents and cross-reference links
- static asset manifests
- media checksums and copy policies
- root output asset references

Output: reference/asset manifest model and docs with examples.

## P15.6 - Permission sandbox for non-core functions

```task
id: MKTT-WP-0015-T006
status: todo
priority: high
state_hub_task_id: "9ef2c516-2cd0-40ba-b270-abefbfd8fc40"
```

Add explicit local permission gates for functions that need:

- filesystem reads or writes
- network access
- external processes
- native content inclusion
- assisted generation
- render/export side effects

Use Markitect-local policy contracts first. flex-auth, OpenFGA, OPA, Cedar,
Keycloak, Entra, or similar systems may be optional adapters, but must not be
required for deterministic function parsing, validation, and rendering of pure
functions.

Output: permission vocabulary, denied-operation diagnostics, and policy tests.

## Exit Criteria

- Core deterministic document functions remain simple and dependency-light.
- Richer functions are optional extensions with declared capabilities.
- Render/export adapters can be tested without live external services.
- Quarkdown interoperability is conceptually supported without direct code
  dependency.
- Typed values, render provenance, references, and assets have clear contracts.
- The extension does not duplicate the dataflow workflow engine.