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.

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.

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

# 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:

> **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

| 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:

```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

pandoc input.md \
  --css=agentman-brand.css \
  --pdf-engine=wkhtmltopdf \
  -o output.pdf

Or use the HTML intermediate:

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:

<!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