Markdown & JSON Formatting Mastery

The results are:
Product A - Revenue: $1.2M, Growth: 12%
Product B - Revenue: $0.8M, Growth: -3%

Note: these figures are from Q3 only.

def calculate_growth(current, previous):
  return (current - previous) / previous * 100

## Q3 Revenue Results

| Product   | Revenue | Growth |
|-----------|---------|--------|
| Product A | $1.2M   | +12%   |
| Product B | $0.8M   | -3%    |

**Note:** These figures reflect Q3 only and are not annualized.

```python
def calculate_growth(current, previous):
    return (current - previous) / previous * 100
```

Formatting is a training signal

Every demonstration response you write, and every AI response you evaluate, teaches the model something about what good output looks like. If expert demonstrations consistently use ## for major sections and fenced code blocks for all code, the model learns that pattern. If demonstrations are inconsistent, the model learns inconsistency and reproduces it. Do not substitute bold text for headings, paste code as plain text, or make fake tables.

The failures that matter most are silent ones. Markdown that looks fine as raw text but renders incorrectly, or JSON that passes a visual scan but breaks a parser downstream, are huge problems. Both are covered here.

Markdown: what platforms enforce

Headers

Use ATX-style headers (hash marks), not underline-style. Use heading levels semantically:

# Page Title (H1) — typically one per document
## Major Section (H2)
### Subsection (H3)
#### Minor subdivision (H4) — use sparingly

The most common mistake is using bold text (**Section Name**) as a substitute for a heading. It looks similar when rendered but has no semantic meaning. It won’t appear in a table of contents, won’t be parsed as a section by downstream tools, and teaches the model that bold equals heading. If the rubric calls for a structured response with sections, use actual headings.

**Summary**
The analysis covers Q3 performance across five product lines...

**Key Findings**
Revenue increased 12% year-over-year...

**Recommendations**
Prioritize investment in product lines 2 and 4...

## Summary
...
## Key Findings
...
## Recommendations
...

Code blocks

Always use fenced code blocks with a language specifier for any code:

```python
def hello(name):
    return f"Hello, {name}"
```

Never use inline backticks for multi-line code. Never paste code as plain text. The language specifier (python, sql, json, bash) enables syntax highlighting and signals to the model what kind of code it is — omitting it is a weaker training signal even when the code itself is correct.

Inline code (single backticks) is for short references within prose: “Use the groupby() method to aggregate.” Not for code blocks.

Tables

Markdown tables require a header row, a separator row, and data rows:

| Column A | Column B | Column C |
|----------|----------|----------|
| Value 1  | Value 2  | Value 3  |
| Value 4  | Value 5  | Value 6  |

Alignment is controlled by colons in the separator row: |:---| (left), |:---:| (center), |---:| (right). Omitting the separator row entirely breaks table rendering in most parsers. The content falls through as plain text with no indication that anything went wrong.

Lists and emphasis

For lists, use consistent indentation (2 or 4 spaces, but consistent throughout the document). Don’t use a numbered list for items with no inherent order, and don’t use bullets for a sequence of steps that must be followed in order. The list type carries meaning.

For emphasis: **bold** for strong emphasis or key terms, *italic* for titles or mild emphasis. Don’t use ALL CAPS. It is inaccessible and not Markdown.

JSON: the rules that break parsers

JSON is the standard format for structured AI outputs, particularly for tool use tasks. An invalid JSON object breaks the entire pipeline downstream silently. There is no warning, just a failed parse. Three categories of errors cover almost everything you’ll encounter.

Quoting and key rules: All strings and all keys must use double quotes. {name: "Alice"} is invalid because the key is unquoted. {'name': 'Alice'} is invalid because single quotes aren’t JSON. {"name": "Alice"} is correct.

Value rules: Booleans are true and false — lowercase, no quotes, not Python’s True/False. Null values are null — not Python’s None, not JavaScript’s undefined. These aren’t style preferences; they’re specification requirements. Any conforming JSON parser rejects the alternatives.

Structural rules: No trailing commas after the last item in an object or array. No comments of any kind. They’re valid in JavaScript but will cause a JSON parse error. If you see comments in AI output, flag it as invalid.

{
  'name': 'Jordan Lee',
  'age': 29,
  'active': True,
  'tags': ['finance', 'analyst'],
}

{
  "name": "Jordan Lee",
  "age": 29,
  "active": true,
  "tags": ["finance", "analyst"]
}

Nested structures

AI tool use tasks often produce nested JSON. Verify that nesting is correct and that arrays contain consistent types:

{
  "results": [
    {
      "id": 1,
      "tags": ["finance", "accounting"],
      "metadata": {
        "confidence": 0.92,
        "reviewed": false
      }
    }
  ]
}

Watch for: inconsistent array element types (["a", 1, null, true] — valid JSON but often a semantic error), deeply nested objects when a flatter structure was requested, missing required keys.

Structured outputs for tool use

In tool use annotation tasks, the AI produces structured outputs that a downstream system parses and acts on. A correct tool-use response looks like this:

{
  "tool": "search_database",
  "parameters": {
    "query": "annual revenue 2023",
    "filters": {
      "industry": "technology",
      "min_employees": 500
    }
  }
}

When evaluating these, check four things: syntactic validity (would this pass a JSON parser?), correct tool name from the schema provided, all required parameters present with the right types, and optional parameters either used correctly or omitted cleanly — not present with a null value when the schema says to omit them.

{"result": None, "success": True}

{"result": null, "success": true}

Quick Reference

• Formatting is a training signal: Inconsistent or incorrect formatting in demonstration responses teaches the model to reproduce that inconsistency. Use ## headings (not bold), fenced code blocks with language specifiers (not plain text), and pipe tables with separator rows (not dashes).
• JSON hard rules: Double-quoted keys and strings, lowercase true/false/null, no trailing commas, no comments. Any of these broken means the JSON is invalid and will fail parsing downstream — not a style issue.
• Bold ≠ heading, None ≠ null, True ≠ true: These are the three substitutions that appear most often in AI output and produce silent failures. Catch them every time.