AI Prompt Engineering · Lesson

Markdown Formatting in Prompts

Headers, bold, code blocks — how to specify rich formatting.

Markdown Formatting in Prompts is a free AI Prompt Engineering lesson on CoddyKit — lesson 3 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the AI Prompt Engineering learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Markdown in AI Output

Markdown is a lightweight text formatting syntax that AI models understand natively. When you ask for markdown-formatted output, the model produces text that renders as rich formatting in compatible environments.

Knowing exactly how to request each markdown element gives you precise control over the structure of every AI-generated document.

Requesting Headers

Markdown headers use hash symbols: # for H1, ## for H2, ### for H3.

Request them explicitly: 'Structure with H2 section headers', 'Use ## for main sections and ### for subsections', or 'Include a single # H1 title at the top.'

Headers create navigable structure in Notion, GitHub, Obsidian, and most documentation tools.

import anthropic

client = anthropic.Anthropic(api_key='sk-ant-your-key-here')

response = client.messages.create(
    model='claude-opus-4-5',
    max_tokens=400,
    messages=[{
        'role': 'user',
        'content': (
            'Write a technical guide outline for "Getting Started with FastAPI". '
            'Structure: one # H1 title at the top, then 4 ## H2 section headers, '
            'each with 2 ### H3 subsection headers beneath it. '
            'Add one sentence of placeholder content under each H3.'
        )
    }]
)
print(response.content[0].text)

Bold and Italic Emphasis

Bold and italic emphasis in markdown:

**bold text** → bold text
*italic text* → italic text
***bold and italic*** → bold and italic

Request: 'Bold all key terms on first use', 'Use italics for product names', or 'Bold the action item in each step.'

import openai

client = openai.OpenAI(api_key='sk-your-key-here')

response = client.chat.completions.create(
    model='gpt-4o',
    messages=[{
        'role': 'user',
        'content': (
            'Explain the concept of idempotency in REST APIs. '
            'Rules:\n'
            '- Bold every technical term on its first occurrence only\n'
            '- Italicize all HTTP method names (GET, POST, PUT, DELETE, PATCH)\n'
            '- 150 words max, flowing prose — no bullets or headers'
        )
    }]
)
print(response.choices[0].message.content)

Code Blocks

Code blocks in markdown use triple backticks with an optional language hint for syntax highlighting:

```python
print('hello')
```

Request: 'Include all code in python code blocks', 'Wrap every command in a bash code block', or 'Show the JSON example in a json code block.'

The language hint enables syntax highlighting in GitHub, VS Code, and documentation sites.

import anthropic

client = anthropic.Anthropic(api_key='sk-ant-your-key-here')

response = client.messages.create(
    model='claude-opus-4-5',
    max_tokens=400,
    messages=[{
        'role': 'user',
        'content': (
            'Show me how to connect to PostgreSQL from Python using psycopg3.\n'
            'Structure:\n'
            '1. Install command in a bash code block.\n'
            '2. Connection example in a python code block with type hints.\n'
            '3. A sample SELECT query in a python code block.\n'
            'Keep each code block under 10 lines. Brief one-sentence intro before each block.'
        )
    }]
)
print(response.content[0].text)

Inline Code

Inline code uses single backticks: `variable_name`. It renders as monospace text within a sentence — perfect for:

Variable names: user_id
Function names: calculate_tax()
Command names: git commit
File paths: /etc/nginx/nginx.conf
HTTP endpoints: /api/v1/users

Request: 'Use inline code formatting for all variable and function names.'

import openai

client = openai.OpenAI(api_key='sk-your-key-here')

response = client.chat.completions.create(
    model='gpt-4o',
    messages=[{
        'role': 'user',
        'content': (
            'Explain the difference between Python list .append() and .extend(). '
            'Rules:\n'
            '- Use inline code for all method names, parameter names, and variable examples\n'
            '- Use a python code block for each demonstration example\n'
            '- Prose sections: max 2 sentences\n'
            '- Do NOT use headers or bullets — flowing prose with code blocks only'
        )
    }]
)
print(response.choices[0].message.content)

Blockquotes

Blockquotes use > at the start of a line. In markdown:

> This is a blockquote.

Use cases: callout boxes, important notes, example dialogues, quoted source material, warnings.

Request: 'Put the most important warning in a blockquote' or 'Use a blockquote for the example scenario.'

import anthropic

client = anthropic.Anthropic(api_key='sk-ant-your-key-here')

response = client.messages.create(
    model='claude-opus-4-5',
    max_tokens=300,
    messages=[{
        'role': 'user',
        'content': (
            'Write a security guide section about SQL injection prevention. '
            'Structure:\n'
            '- 2-sentence explanation of the risk\n'
            '- One blockquote containing a real example of vulnerable code (as a note/warning)\n'
            '- 3 bullet points on how to prevent it\n'
            '- One blockquote containing the safe alternative code pattern'
        )
    }]
)
print(response.content[0].text)

Nested Lists in Markdown

Nested markdown lists use indentation (2 or 4 spaces) to create hierarchy:

- Main item
  - Sub-item
  - Sub-item
    - Sub-sub-item

Request: 'Create a two-level nested list with X main items and Y sub-items each' or 'Use nested bullets to show the relationship between categories and examples.'

import openai

client = openai.OpenAI(api_key='sk-your-key-here')

response = client.chat.completions.create(
    model='gpt-4o',
    messages=[{
        'role': 'user',
        'content': (
            'Create a 2-level nested markdown list of AWS services for a web startup. '
            'Level 1: 4 service categories (Compute, Storage, Database, Networking). '
            'Level 2: 3 specific services under each category with a 5-word description. '
            'Format: markdown nested bullets with proper indentation.'
        )
    }]
)
print(response.choices[0].message.content)

Links and Images

Markdown links: [link text](URL)
Markdown images: ![alt text](image-URL)

AI models can generate placeholder links with meaningful text: 'Include markdown links to relevant documentation — use placeholder URLs like [official docs](https://example.com).'

For documentation with diagram placeholders: 'Include an image placeholder with meaningful alt text.'

import anthropic

client = anthropic.Anthropic(api_key='sk-ant-your-key-here')

response = client.messages.create(
    model='claude-opus-4-5',
    max_tokens=300,
    messages=[{
        'role': 'user',
        'content': (
            'Write a README section for a Python open-source project called "sqlens". '
            'Include:\n'
            '- An image placeholder for a demo screenshot: ![Demo screenshot](docs/demo.png)\n'
            '- At least 2 markdown links: one to the PyPI page, one to the documentation\n'
            '- A badge placeholder using an image link\n'
            '- 3 bullet points of key features\n'
            'Use realistic placeholder URLs (pypi.org/project/sqlens etc).'
        )
    }]
)
print(response.content[0].text)

Horizontal Rules and Dividers

Horizontal rules use three dashes (---), asterisks (***), or underscores (___).

Use them to visually separate major document sections. Request: 'Add a --- horizontal rule between each major section' or 'Separate the three sections with markdown dividers.'

Horizontal rules render in most markdown environments and help readers navigate long documents.

import openai

client = openai.OpenAI(api_key='sk-your-key-here')

response = client.chat.completions.create(
    model='gpt-4o',
    messages=[{
        'role': 'user',
        'content': (
            'Write a mini technical specification document for a user authentication API. '
            'Include exactly 3 sections: Overview, Endpoints, Security Requirements. '
            'Separate each section with a --- horizontal rule. '
            'Each section: ## H2 header + 3-5 bullet points of content. '
            'Under Endpoints: use inline code for all route paths and HTTP methods.'
        )
    }]
)
print(response.choices[0].message.content)

When Markdown Does Not Render

Markdown only helps when the output environment renders it. Markdown does NOT render in:

Plain text email clients (raw asterisks appear)
SMS messages
Most CRM notes fields
Voice output (text-to-speech)
Legacy systems expecting plain text

For these contexts, explicitly request plain text instead. We cover this in the next lesson.

import anthropic

client = anthropic.Anthropic(api_key='sk-ant-your-key-here')

# Check if environment renders markdown before requesting it
rendering_environments = {
    'GitHub':     True,
    'Notion':     True,
    'Obsidian':   True,
    'VS Code':    True,
    'Gmail body': False,  # some markdown, not all
    'Outlook':    False,
    'SMS':        False,
    'Plain text file': False,
}

print('Markdown rendering support:')
for env, renders in rendering_environments.items():
    status = 'RENDERS' if renders else 'DOES NOT RENDER'
    print(f'  {env:<20} {status}')

# Decision: use markdown only when you know it renders
use_markdown = True  # set based on your environment

format_instruction = (
    'Use markdown headers, bold, and code blocks.' if use_markdown
    else 'Plain text only — no markdown symbols.'
)
print('\nFormat instruction:', format_instruction)

Combining Markdown Elements

Production-quality AI-generated documents combine multiple markdown elements. A well-structured technical document might use:

# H1 title + ## H2 sections
**bold** key terms on first use
Code blocks with language hints for all code
Inline code for all variable/function names
Bullet lists for requirements; numbered lists for steps
Blockquotes for warnings and important notes
--- dividers between major sections

import openai

client = openai.OpenAI(api_key='sk-your-key-here')

response = client.chat.completions.create(
    model='gpt-4o',
    messages=[{
        'role': 'user',
        'content': (
            'Write a mini developer guide for the requests Python library. '
            'Use all of the following markdown elements:\n'
            '- # H1 title at the top\n'
            '- ## H2 sections: Installation, Basic Usage, Error Handling\n'
            '- Bold all key terms on first use\n'
            '- Code blocks with python/bash language hints\n'
            '- Inline code for all function names\n'
            '- One blockquote warning about timeout best practice\n'
            '- --- between each section\n'
            'Max 300 words total.'
        )
    }]
)
print(response.choices[0].message.content)

Knowledge Check

A developer is building an AI assistant that outputs content to be displayed in a terminal using print() — no web UI, no markdown renderer. They ask the AI for a feature explanation and get output full of asterisks and hash symbols. What should they add to the system message to fix this?

Markdown in Prompts — Recap

Markdown formatting gives your AI-generated documents professional structure. Key elements to request:

Headers: # H1, ## H2, ### H3 — for navigable document structure
Emphasis: **bold** for key terms, *italic* for special names
Code blocks: triple-backtick with language hint for syntax highlighting
Inline code: single backtick for variable names, commands, paths
Blockquotes: > prefix for warnings, callouts, quoted content
Nested lists: indented bullets for hierarchical information

Only use markdown when you know the output environment renders it.

Frequently asked questions

Is the “Markdown Formatting in Prompts” lesson free?

Yes — the full text of “Markdown Formatting in Prompts” is free to read here on the web, and the AI Prompt Engineering course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the AI Prompt Engineering course, upgrade to CoddyKit PRO.

What will I learn in “Markdown Formatting in Prompts”?

Headers, bold, code blocks — how to specify rich formatting. You practise AI Prompt Engineering with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start AI Prompt Engineering?

No prior experience is required. AI Prompt Engineering on CoddyKit is structured for beginners through advanced learners; this is — lesson 3 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Markdown Formatting in Prompts” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this AI Prompt Engineering lesson?

Yes. Every AI Prompt Engineering lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to AI Prompt Engineering