agentman-md-style

# Agentman Markdown Style Guide

## Overview

Markdown is plain text — styling only applies at render time. This skill covers two layers:

1. **Structure conventions** — heading hierarchy, callout patterns, table formatting, voice rules (applies everywhere, even raw `.md`)
2. **CSS rendering spec** — the brand stylesheet to inject when converting MD → HTML or MD → PDF

**The brand identity is quiet confidence** — charcoal suits, not fire trucks. The same terracotta/charcoal system used in PPTX and DOCX applies here.

## When to Use

- Generating `.md` files for reports, READMEs, docs sites, or internal documentation
- Rendering Markdown to HTML with Agentman branding
- Converting Markdown to PDF via Pandoc with brand styles
- Creating Claude artifacts with branded Markdown content
- Any task that produces `.md` output AND involves Agentman branding

## Rendering Target Decision Tree

```
Where will this render?
├── GitHub / Notion / Obsidian / raw viewer
│   → Apply structure conventions only (no CSS possible)
├── HTML (browser, docs site, Claude artifact)
│   → Inject references/css.md stylesheet
├── PDF via Pandoc
│   → Use Pandoc HTML pipeline: md → html (with CSS) → pdf
└── Docusaurus / MkDocs / GitBook
    → Use CSS overrides in site config, follow structure conventions
```

## Font Strategy

**Two fonts. One rule: Inter for headings, system sans-serif for body.**

| Element | Font | Notes |
|---------|------|-------|
| H1, H2, H3 | **Inter** | Loaded via Google Fonts in CSS |
| Body, tables, code labels | **system-ui / Calibri** | Platform-native; no embedding needed |
| Code blocks | **monospace** | System default |

In CSS, Inter is loaded via `@import` from Google Fonts. Body falls back gracefully to Calibri → Arial → system-ui across platforms.

**Full CSS implementation:** See `references/css.md`

## Color System (Quick Reference)

Same palette as PPTX and DOCX skills.

| Token | Hex | Usage |
|-------|-----|-------|
| brand-500 | `#CC785C` | Headings, links, callout borders, table headers |
| brand-400 | `#D97757` | H2 accent color, highlighted text |
| brand-75 | `#F0EEE6` | Callout backgrounds, alternate table rows |
| brand-50 | `#FAF9F5` | Page background (light mode) |
| charcoal-950 | `#141413` | Primary body text |
| charcoal-900 | `#292322` | H1 color |
| charcoal-800 | `#3D3735` | H2, H3 color |
| slate-600 | `#475569` | Secondary text, captions |
| slate-500 | `#64748B` | Footer, metadata |

Banned: blue, green, red, navy, pure black (`#000000`), Word/default grays, gradients.

**Full color mapping:** See `references/css.md`

## Structure Conventions (Applies Everywhere)

### Heading Hierarchy

```markdown
# Document Title        ← H1: one per document, top only
## Major Section        ← H2: primary content divisions
### Subsection          ← H3: sub-topics within a section
#### Detail (rare)      ← H4: use sparingly, never deeper
```

**Rules:**
- One H1 per document — always the first element
- Never skip levels (no H1 → H3)
- H4 and deeper: avoid. Restructure instead.
- Headings are sentence case, not title case (except H1)

### Callout Blocks

Markdown has no native callout syntax. Use blockquote convention:

```markdown
> **Note:** Supporting context that doesn't interrupt the main flow.

> **Key insight:** A major point worth highlighting — use sparingly.

> **Warning:** Something the reader must not overlook.
```

In rendered HTML, these become styled callout blocks via CSS. In raw Markdown, they read naturally as blockquotes.

### Tables

```markdown
| Metric | Value | Change |
|--------|-------|--------|
| Revenue | $4.2M | +12% |
| Margin | 34% | +2pp |
```

**Rules:**
- Always include header row with `---` separator
- Left-align text columns, right-align or center numeric columns
- Keep tables narrow — 3–5 columns max
- Use em dash (`—`) for empty/N/A cells, not blank

### Lists

**Unordered:** Use `-` (not `*` or `+`) for consistency.

**Ordered:** Use `1.` numbering throughout (Markdown auto-increments).

**Nesting:** Maximum 2 levels. Deeper → restructure as a section.

### Code Blocks

Always specify the language:

````markdown
```javascript
const result = agentmanTable(headers, data);
```
````

Never use inline code for multi-line content.

### Horizontal Rules

Use `---` sparingly — only for major document section breaks, never within sections.

### Emphasis

- `**Bold**` — key terms, important phrases (1–2 per paragraph max)
- `_Italic_` — titles of external works, technical terms on first use
- Never bold + italic together

## Implementation Workflow

### For Raw Markdown (GitHub, Notion, etc.)
1. Follow structure conventions above
2. Use callout blockquote pattern for highlights
3. Keep tables ≤ 5 columns
4. No CSS needed — structure carries the brand

### For HTML Output
1. Load `references/css.md` stylesheet
2. Inject as `<style>` tag or linked `.css` file
3. Render Markdown to HTML (marked.js, markdown-it, Pandoc, etc.)
4. The CSS handles Inter loading, color system, callout styling

### For PDF via Pandoc
```bash
pandoc input.md \
  --css=agentman-brand.css \
  --pdf-engine=wkhtmltopdf \
  -o output.pdf
```
Or use the HTML intermediate:
```bash
pandoc input.md -t html5 --css=agentman-brand.css -o intermediate.html
# Then print to PDF via browser or wkhtmltopdf
```

### For Claude Artifacts
Wrap rendered HTML with the brand stylesheet inline:
```html
<!DOCTYPE html>
<html>
<head>
  <style>/* paste contents of references/css.md here */</style>
</head>
<body>
  <!-- rendered markdown content -->
</body>
</html>
```

## Critical Reminders

### Always
- One H1 per document
- Inter for H1–H3 (via CSS), system-ui/Calibri for body
- Sentence case headings (except H1)
- Specify language on all code blocks
- Use `-` for unordered lists

### Never
- Skip heading levels
- Use H4+ (restructure instead)
- Use blue, green, red, or pure black
- Use bold + italic together
- Nest lists more than 2 levels
- Use tables wider than 5 columns

**CSS implementation:** See `references/css.md`
**Structure examples:** See `references/structure.md`