Content Formats

Context Repo treats Markdown and HTML as equally valid content formats. Every document and prompt you store can be written in either format — or a mix of both — and the platform renders it correctly for whichever consumer is reading it: an AI agent retrieving context over MCP, or a human viewing it in the dashboard.

Two Formats, Two Audiences

The distinction comes down to who is reading the content and why:

Markdown: the agent-native format

Markdown is the natural language of LLMs. When an agent retrieves a document through get_document or find_items, it receives the raw content as stored — and Markdown content means the agent spends its context window on substance, not markup.

Use Markdown when:

• Writing prompt templates that agents will inject into conversations
• Authoring reference material that agents retrieve during workflows (runbooks, instructions, checklists)
• Creating searchable knowledge where embedding quality matters — fewer markup tokens means denser semantic signal

HTML: the human-native format

HTML gives you full control over layout and visual presentation. Inline styles, grid layouts, and embedded SVG elements all render faithfully in the dashboard preview and on public share pages.

Use HTML when:

• Building visual reports with charts, gauges, progress rings, and status cards
• Creating shareable presentations that need email-quality formatting
• Designing dashboard-style documents that humans scan at a glance — pool chemistry reports, project status boards, wellness scorecards
• Embedding data visualizations using inline <svg> elements with gradients, arcs, and styled text

How It Works

The rendering pipeline handles both formats automatically:

• Markdown flows through the standard remark/rehype pipeline — headings become semantic HTML, code blocks get syntax highlighting, tables render properly
• HTML passes through rehype-raw, which preserves your markup as-is, then through a safety layer (rehype-sanitize) that strips script handlers and dangerous URLs while keeping presentational elements intact
• Inline SVG elements are converted to <img> elements with data:image/svg+xml source URLs — browsers render them as static images, which is inherently safe (no script execution)
• Indented HTML (4+ space indent) is treated as markup, not code — so nested <div> structures inside a markdown document render as DOM, not as <pre><code> blocks

You don't need to configure anything or pick a mode. The pipeline detects and handles each format correctly.

Mixing Formats

A single document can contain both Markdown and HTML. The most common pattern:

1. Markdown front matter — title, description, and narrative sections written in Markdown for agent readability
2. HTML visual sections — embedded charts, styled cards, or layout grids wrapped in <div> elements
3. Markdown conclusions — final notes, next steps, and call-to-action in Markdown

When an agent retrieves this mixed document, it sees both the narrative text and the HTML markup. The HTML adds token overhead, but the agent can still parse and reason about the substantive content. When a human views the same document in the dashboard, they see the narrative rendered as formatted text and the HTML sections rendered as visual components.

Choosing the Right Format

A simple decision framework:

• Will an agent consume this? Lean toward Markdown.
• Will a human view this in a browser? Lean toward HTML.
• Both? Mix — Markdown for the substance, HTML for the visual sections.
• Is it a prompt template? Always Markdown — agents inject prompts verbatim, and HTML markup adds noise.

SVG Support

Inline <svg> elements are a first-class feature. You can embed SVG directly in your HTML content and it renders in the dashboard preview as a static image — with full support for:

• Gradients (<linearGradient>, <radialGradient>)
• Arc paths and stroke-dashoffset gauges
• Styled text (font-weight, letter-spacing, text-anchor)
• Grid layouts with SVG elements inside styled <div> containers

SVGs are rendered as images, so they don't execute scripts or load external resources. This makes them safe for user-authored content while still producing rich data visualizations — status gauges, progress rings, bar charts, and flow diagrams all render correctly.

Related Pages