Build and release Dataface markdown integrations for MkDocs and popular doc tools

Problem

After the markdown report contract is stable, ship supported integrations for MkDocs and other common markdown/doc ecosystems using thin adapters over Dataface rendering, with docs, examples, packaging, and release guidance rather than making generic markdown extension support the core architecture.

Context

This task is intentionally post-core. The markdown report contract should land first inside Dataface itself, with .md files translating into the canonical face model. Only after that contract is stable should Dataface ship integrations for external markdown/doc ecosystems.

The likely adoption path is not "make generic markdown extension syntax the core product model." Instead it is:

• Dataface owns the canonical report/board/chart model
• Dataface exposes a reusable fragment-rendering path for chart/board embeds
• external ecosystems such as MkDocs use thin adapters on top of that

MkDocs is the obvious first target because it is already common in docs-as-code workflows, but the task should also consider a small set of other popular tools where the same pattern could apply once the API is stable.

Constraints:

• Do not distort core architecture just to fit one docs platform.
• Prefer thin adapters/macros/plugins over a sprawling platform-specific feature matrix.
• Ship docs, examples, packaging, and release guidance together with any integration.
• This work depends on the markdown report contract and naming decisions being stable first.

Possible Solutions

Option A - Build separate ad hoc macros/plugins per platform with no shared API

Ship one-off integrations for MkDocs, blogs, and other tools independently.

• Pros: fast to start on a single target.
• Cons: duplicated logic, inconsistent behavior, and no stable integration contract.

Option B - Recommended: build a shared fragment-rendering adapter surface, then ship MkDocs first

Define a reusable way to render chart/board fragments from Dataface sources, then ship a first-class MkDocs plugin or macro/directive package on top of that. Use the same contract for later adapters to other popular tools.

• Pros: keeps core/product architecture clean, gives a strong first integration, and avoids platform-specific reinvention.
• Cons: requires a little more up-front API discipline before the first plugin ships.

Option C - Make a generic markdown extension the primary product surface

Optimize the core feature around being embedded in arbitrary markdown ecosystems first.

• Pros: sounds integration-friendly.
• Cons: backwards architecture choice for Dataface; forces core design around adapters instead of around canonical report/board behavior.

Plan

1. Confirm the stable core contract inherited from the markdown report and naming tasks.
2. Define a small reusable fragment-rendering API for "render chart/board from source path" that external adapters can call.
3. Pick the first supported target, likely MkDocs, and define the authoring surface: - plugin - macro/directive syntax - path resolution rules - build-time caching behavior
4. Implement and document the first supported integration with examples and a sample docs project.
5. Package and release the integration in a way that is supportable, including versioning guidance and compatibility notes.
6. Evaluate the next 1-2 popular targets only after the first integration proves the API shape.

Implementation Progress

QA Exploration

QA should include at least one sample docs site build and visual/manual verification that embedded charts or boards render correctly in the host tool. Browser exploration may be useful for the sample integration demo, but the primary proof is a working external-docs build.

• [ ] QA exploration completed (or N/A for non-UI tasks)

Review Feedback

• [ ] Review cleared