> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Markdown Chunking

> Split Markdown documents by heading structure or an approximate character target.

`MarkdownChunking` returns content at or below `chunk_size` as one chunk in its default mode. For longer content, it uses Unstructured to partition Markdown and group the resulting elements toward `chunk_size`. Set `split_on_headings=True` to split on every ATX heading from H1 through H6. Set an integer from `1` to `6` to split on ATX headings through that level.

**1. Create a Python file**

```python markdown_chunking.py theme={null}
from agno.agent import Agent
from agno.knowledge.chunking.markdown import MarkdownChunking
from agno.knowledge.knowledge import Knowledge
from agno.knowledge.reader.markdown_reader import MarkdownReader
from agno.vectordb.pgvector import PgVector

db_url = "postgresql+psycopg://ai:ai@localhost:5532/ai"

knowledge = Knowledge(
    vector_db=PgVector(table_name="recipes_markdown_chunking", db_url=db_url),
)

knowledge.insert(
    url="https://raw.githubusercontent.com/agno-agi/agno/v2.7.2/README.md",
    reader=MarkdownReader(
        name="Markdown Chunking Reader",
        chunking_strategy=MarkdownChunking(chunk_size=1000),
    ),
)

agent = Agent(
    knowledge=knowledge,
    search_knowledge=True,
)

agent.print_response("What is Agno?", markdown=True)
```

<Snippet file="create-venv-step.mdx" />

**2. Install dependencies**

```bash theme={null}
uv pip install -U agno sqlalchemy psycopg pgvector "unstructured<0.18.31" markdown openai
```

**3. Export your OpenAI API key**

<Snippet file="set-openai-key.mdx" />

<Snippet file="run-pgvector-step.mdx" />

**4. Run the script**

```bash theme={null}
python markdown_chunking.py
```

## Choose a Mode

| `split_on_headings` | Behavior |
| - | - |
| `False` | Keep short input as one chunk; partition and group longer input with Unstructured |
| `True` | Start a chunk at every ATX heading from H1 through H6, regardless of document size |
| `1` to `6` | Start a chunk at ATX headings through the selected level, regardless of document size |

In heading mode, sections longer than `chunk_size` are split by paragraphs, then by words, and repeat an existing heading. A long indivisible word or prepended overlap can make the final chunk longer than `chunk_size`. Overlap is prepended without an added separator.

## Markdown Chunking Params

<Snippet file="chunking-markdown.mdx" />

## Developer Resources

* [Chunking overview](https://agno-v2.mintlify.site/knowledge/concepts/chunking/overview.md)
* [Chunking strategies examples](https://agno-v2.mintlify.site/examples/knowledge/building-blocks/chunking-strategies.md)
* [Markdown reader](https://agno-v2.mintlify.site/knowledge/concepts/readers/markdown-reader.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.