> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upsonic.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Markdown Loader

> Load Markdown files with front matter and code block support

## Overview

Markdown loader processes Markdown files with support for YAML front matter parsing, code block extraction, and heading-based document splitting. Preserves structure and metadata.

**Loader Class:** `MarkdownLoader`

**Config Class:** `MarkdownLoaderConfig`

## Install

<Note>
  Install the Markdown loader optional dependency group:

  ```bash theme={null}
  uv pip install "upsonic[markdown-loader]"
  ```
</Note>

## Examples

```python theme={null}
from upsonic import Agent, Task, KnowledgeBase
from upsonic.loaders.markdown import MarkdownLoader
from upsonic.loaders.config import MarkdownLoaderConfig
from upsonic.embeddings import OpenAIEmbedding, OpenAIEmbeddingConfig
from upsonic.text_splitter.recursive import RecursiveChunker, RecursiveChunkingConfig
from upsonic.vectordb import ChromaProvider, ChromaConfig, ConnectionConfig, Mode

# Configure loader
loader_config = MarkdownLoaderConfig(
    parse_front_matter=True,
    include_code_blocks=True,
    split_by_heading="h2"
)
loader = MarkdownLoader(loader_config)

# Setup KnowledgeBase
embedding = OpenAIEmbedding(OpenAIEmbeddingConfig())
chunker = RecursiveChunker(RecursiveChunkingConfig())
vectordb = ChromaProvider(ChromaConfig(
    collection_name="markdown_docs",
    vector_size=1536,
    connection=ConnectionConfig(mode=Mode.IN_MEMORY)
))

kb = KnowledgeBase(
    sources=["document.md"],
    embedding_provider=embedding,
    vectordb=vectordb,
    loaders=[loader],
    splitters=[chunker]
)

# Query with Agent
agent = Agent("anthropic/claude-sonnet-4-5")
task = Task("Extract all code examples", context=[kb])
result = agent.do(task)
print(result)
```

## Parameters

| Parameter                      | Type                            | Description                           | Default | Source   |
| ------------------------------ | ------------------------------- | ------------------------------------- | ------- | -------- |
| `encoding`                     | `str \| None`                   | File encoding (auto-detected if None) | None    | Base     |
| `error_handling`               | `"ignore" \| "warn" \| "raise"` | How to handle loading errors          | "warn"  | Base     |
| `include_metadata`             | `bool`                          | Whether to include file metadata      | True    | Base     |
| `custom_metadata`              | `dict`                          | Additional metadata to include        | {}      | Base     |
| `max_file_size`                | `int \| None`                   | Maximum file size in bytes            | None    | Base     |
| `skip_empty_content`           | `bool`                          | Skip documents with empty content     | True    | Base     |
| `parse_front_matter`           | `bool`                          | Parse YAML front matter               | True    | Specific |
| `include_code_blocks`          | `bool`                          | Include code block content            | True    | Specific |
| `code_block_language_metadata` | `bool`                          | Add code block language as metadata   | True    | Specific |
| `heading_metadata`             | `bool`                          | Extract headings and add to metadata  | True    | Specific |
| `split_by_heading`             | `"h1" \| "h2" \| "h3" \| None`  | Split file by heading level           | None    | Specific |