Docmark Specification

1. Overview

Docmark is plain CommonMark/GFM Markdown plus two additions: YAML frontmatter for document metadata, and Pandoc-style attributes for layout components.

Any Docmark file is still valid, readable Markdown. Unsupported tools will render it as plain text with a few harmless-looking symbols ({.callout}, :::), while supporting tools — like the CMIQ Documentation Converter app — render it as a fully styled document adhering to the CMIQ Health Brand System.

2. Document Metadata: YAML Frontmatter

Every document may open with a YAML block bounded by --- lines. This drives the branded title page.

---
title: "Reversing Sarcopenia and Insulin Resistance in Older Adults"
subtitle: "The Synergy of Dietary Protein and Progressive Resistance Training"
kicker: "Clinical & Nutritional Science Reference"
date: "August 2026"
meta:
  - label: Scope
    value: >-
      Evidence-based guidance on protein dosing, the leucine threshold,
      and progressive resistance training protocols for mitigating
      age-related muscle loss and insulin resistance
  - label: Audience
    value: "Clinicians, exercise physiologists, dietitians, and informed older-adult patients"
---

2.1 Fields

YAML frontmatter fields
Field	Required	Purpose
`title`	Yes	Large Cormorant Garamond serif headline on the title page
`subtitle`	No	Italic line beneath the title
`kicker`	No	Small uppercase eyebrow label in DM Sans (Secondary `#b53325` color) above the title
`date`	No	Shown in the metadata block; free text (`"August 2026"`, `"Draft — 3 Sept 2026"`)
`meta`	No	An ordered list of `label`/`value` pairs rendered under a 2px Primary (`#ecbb48`) divider rule. Use this for Scope, Audience, Author, Version, Client, Confidentiality.
`style` / `css`	No	Multiline CSS string for document-specific styling overrides (e.g. `h3 { color: #b53325; }`).

If title is omitted, the renderer falls back to the first # heading in the body and no dedicated title page is generated — the document starts directly with body content. This keeps memos and short notes from being forced into a title-page format.

2.2 Why frontmatter, not headings

Metadata like “Audience” or “Scope” is a document property, not a section of content — using an H1 for it (as in # Audience {#audience}) confuses tools that build tables of contents, outlines, or accessibility trees from heading structure. YAML frontmatter is what Pandoc, Jekyll, Hugo, Docusaurus, and most static-site/document tooling already use for this exact purpose, so Docmark follows that convention rather than inventing a new one.

2.3 Document-Specific Custom Styling

Authors can customize or override default document styles for a specific .md file in two clean ways:

Via YAML Frontmatter (style or css): Add a multiline style: or css: block to frontmatter. These rules are injected into the document’s <head> after the base CMIQ theme:
```
---
title: "Executive MASLD Brief"
style: |
  h3 { color: #b53325; }
  .callout { border-left-color: #b53325; }
---
```
Via Embedded <style> Tags in Markdown: Include standard <style> blocks anywhere inside the Markdown file body:
```
<style>
  h3 { color: #b53325; }
</style>
```

3. Heading Attributes

Any heading may carry an {...} attribute block at the end of its text, using Pandoc’s header attribute syntax:

## References {.reference-list}

## Contraindications {.appendix #contra}

3.1 Syntax

#some-id — sets the element’s id (for deep links/anchors). At most one per heading.
.some-class — adds a CSS class. Multiple classes are allowed: {.callout .no-break}.
Order doesn’t matter; separate tokens with spaces: {#contra .appendix}.

3.2 Scoping

A heading’s attributes apply to that heading and everything until the next heading of the same or higher level — i.e., an {.reference-list} on an H2 styles that whole section, not just the heading text. This lets one attribute govern a section’s content (a reference list’s type size, an appendix’s numbering) without marking up every paragraph inside it.

4. Fenced Divs (Block Components)

For content that isn’t a full section — a callout in the middle of a paragraph flow, a forced page break, a stat highlight — wrap it in a fenced div, also from Pandoc’s syntax:

::: callout
Older adults should aim for 30–45 g of protein per meal, not back-loaded into a single dinner.
:::

Opens and closes with ::: on their own line.
The word(s) after the opening ::: are treated the same as heading attributes: bare words are classes (::: callout = {.callout}); :::{.callout #warn-1} form is also accepted.
Content inside is ordinary Markdown, parsed recursively (so a callout can contain a list, bold text, even a nested table).
Fenced divs can nest by using longer fences on the outer block (:::: outside, ::: inside), though most documents won’t need this.

5. Table Captions

A line immediately after a table, starting with :, becomes a caption (Pandoc table-caption syntax). It accepts the same attribute block:

| Food | Protein (g) | Leucine (g) |
|---|---|---|
| Chicken breast (4 oz) | 35 | 2.7 |

: Leucine content by food source {.compact}

6. Built-In Component Vocabulary

These classes are recognized out of the box. Unrecognized classes pass through unchanged as CSS classes on the rendered element, so authors and downstream stylesheets can extend the system without the renderer rejecting anything (“fail open”).

Built-in component classes
Class	Applies to	Effect	CMIQ Health Style
`.callout`	fenced div	Highlighted key takeaway box	Primary `#ecbb48` 4px left accent bar, soft `#fdfcf7` background
`.callout-warning`	fenced div	Caution and safety alert box	Secondary `#b53325` 4px left accent bar, soft `#fdf6f5` background, “CAUTION” label
`.stat`	fenced div	Large figure treatment	Large centered number in Cormorant Garamond 38pt (Secondary `#b53325`), top border in Primary `#ecbb48`
`.reference-list`	heading (section scope)	Bibliography list	Compact numbered list in DM Sans 9.6pt
`.appendix`	heading (section scope)	Appendix section	Prepends "Appendix — " in muted accent color
`.no-break`	heading, fenced div, or table caption	Page-break avoidance	Forces `break-inside: avoid` for PDF/print rendering
`.page-break`	empty fenced div	Hard page break	Forces a hard page break at that point
`.two-col`	fenced div	Two-column layout	Lays out content in two side-by-side flex columns
`.compact`	table caption	Dense table padding	Denser padding (1.8mm) and smaller type (8.4pt)

7. CMIQ Health Brand System Alignment

Docmark documents rendered by CMIQ tooling automatically conform to the CMIQ Health Brand System (Montserrat Protocol) as defined in cmiqhealth-webpages-skill.md.

7.1 Brand Identity & Title Page Header

Every cover/title page rendered from YAML frontmatter automatically includes the official CMIQ Health brand mark at the top:

Logo Asset: Verbatim CMIQ SVG mark (#e4a224 gold and #b53325 red paths).
Wordmark: CMIQ in Montserrat (font-weight 600, #0f1210) + Health in light italic (font-style italic, font-weight 300, Primary #ecbb48).

7.2 Typography System

Headings & Hero Titles: 'Cormorant Garamond', serif — large typographic scale with elegant serif authority.
Body & UI Text: 'DM Sans', sans-serif — clean, highly readable sans-serif for body narrative, table cells, and metadata.
Brand Wordmark: 'Montserrat', sans-serif — geometric structure for brand assets and logos.

7.3 Color Palette Tokens

Primary (#ecbb48): Core brand accent, top border rule on title page, H2 section underline, table header border, callout left border, stat container top border.
Secondary (#b53325): Warning callout accent bar and “CAUTION” label, kicker eyebrow text, stat highlight numbers, H4 subsection titles, hyperlinked text.
Surface / Dark Ink (#0f1210): Main document title, H2 heading text, table header background (#263028), strong text emphasis.
Accent 1 (#263028): Dark table header background, container mid-tones.
Accent 2 / Muted (#66756f / #dde4e0): Table cell borders, caption text, page header/footer metadata.

8. Full Example

---
title: "Reversing Sarcopenia and Insulin Resistance in Older Adults"
subtitle: "The Synergy of Dietary Protein and Progressive Resistance Training"
kicker: "Clinical & Nutritional Science Reference"
date: "August 2026"
meta:
  - label: Scope
    value: "Evidence-based guidance on protein dosing and resistance training for older adults"
  - label: Audience
    value: "Clinicians, exercise physiologists, dietitians"
---

## 1. Executive Summary

Skeletal muscle is the body's largest organ by mass...

::: stat
### 80%
of postprandial glucose disposal happens in skeletal muscle
:::

## 4.3 Concrete Exercise Parameters

| Parameter | Recommendation |
|---|---|
| Frequency | 2–3 nonconsecutive days per week |
| Intensity | 70–85% of 1RM |

: NSCA-derived training parameters {.no-break}

::: callout-warning
Medical screening is prudent for older adults with known cardiovascular disease before beginning a resistance program.
:::

## 7. Scientific References {.reference-list}

1. Bauer J, Biolo G, Cederholm T, et al. ... *JAMDA*. 2013;14(8):542–559.
2. Deutz NEP, et al. ... *Clinical Nutrition*. 2014;33(6):929–936.

9. Design Philosophy

Degrade gracefully. A Docmark file opened in a plain-text editor, GitHub preview, or vanilla Markdown renderer should still read cleanly — frontmatter renders as a fenced code block or is ignored, {.class} looks like odd-but-harmless trailing text, ::: fences look like stray punctuation around otherwise normal paragraphs.
Don’t invent syntax that already has a standard. Every extension here (frontmatter, header attributes, fenced divs, table captions) is lifted directly from Pandoc’s Markdown, which is the most widely implemented Markdown superset. This maximizes the chance that other tools (Pandoc itself, static site generators, editors like Obsidian with plugins) already understand parts of a Docmark file.
Fail open on unknown classes. The component vocabulary in Section 6 is a starting set, not a whitelist. Renderers pass through unrecognized classes as plain CSS classes rather than stripping or rejecting them.
Align with brand standards. The visual presentation produced by supporting renderers is governed by the CMIQ Health Brand System, ensuring science-backed clinical authority is paired with polished visual precision.