Module 1: Markdown & TOML/JSON Basics

Before building chatbots, you need to understand how to communicate effectively with AI. This module covers markdown (the most efficient format for AI communication) and configuration formats (TOML vs JSON).

What is Markdown?

Markdown is a lightweight text formatting syntax. Unlike Word documents or PDFs (which contain complex binary formatting), markdown is plain text with simple symbols that AI can parse efficiently.

Why AI Prefers Markdown

Tokens are the basic units AI models use to process text. More tokens = more cost = slower processing. Markdown minimizes tokens while preserving structure.

Basic Markdown Syntax

Headers

# This is a main header (H1)
## This is a subheader (H2)
### This is a section header (H3)

Bold & Italics

**This text is bold**
*This text is italic*
***This text is both bold and italic***

Lists

- Item one
- Item two
  - Nested item
  - Another nested

1. First numbered item
2. Second numbered item

Code Blocks (Essential for AI!)

Triple backticks create code blocks that AI recognizes as structured content:

```
# Example Python code
def hello():
    print("Hello, AI!")
```

This is especially useful when you want AI to:

• Generate code snippets
• Understand structured data examples
• Preserve exact formatting

Links & Images

[Link text](https://example.com)
![Image alt text](image-url.png)

TOML vs JSON: Which to Use?

When feeding AI context about yourself or your project, you have two main options:

JSON (JavaScript Object Notation)

{
  "user_profile": {
    "technical_ability": "beginner",
    "operating_system": "Windows 11",
    "tools": ["VSCode", "Python 3.11"]
  }
}

TOML (Tom’s Obvious, Minimal Language)

[user_profile]
technical_ability = "beginner"
operating_system = "Windows 11"
tools = ["VSCode", "Python 3.11"]

Comparison

When to Use Each

Use TOML for:

• Chatbot directives (your profile, instructions)
• Configuration you want AI to understand
• Anything with comments/explanations

Use JSON for:

• API responses
• Structured data from tools
• When a specific format is required

Practical Exercise

Create a simple markdown file introducing yourself to an AI:

# My AI Profile

## About Me
- **Technical ability**: beginner
- **Operating system**: Windows 11
- **Goal**: Learn web scraping

## My First AI Prompt
I want to scrape the Zapier help forum to build a specialist chatbot.
Can you help me get started?

## Key Takeaways

1. **Markdown is token-efficient** - AI processes it faster and cheaper
2. **Triple backticks** create code blocks AI recognizes instantly
3. **TOML is human-friendly** - Great for directives and profiles
4. **JSON is machine-friendly** - Great for APIs and structured data

## Next Steps

Ready to set up your toolkit? Continue to [Module 2: AI Toolkit Setup](/learn/ai-fundamentals/module-2-toolkit-setup)