Skip to content

Blocks

Notionary provides comprehensive support for all Notion block types through two powerful approaches. Each block type can be created, modified, and converted between Markdown and Notion format seamlessly.

Note: The block APIs documented in this section are used within the append_markdown() and replace_content() methods of NotionPage. These methods accept either markdown strings or MarkdownBuilder functions to create rich content.

Two Ways to Create Content

1. Direct Markdown Syntax

Use Notionary's extended Markdown syntax directly:

# Simple markdown string
await page.append_markdown("""
# Welcome to Notionary

[callout](This is important information "💡")

## Features
- Easy to use
- Powerful API
- Great documentation
""")

2. Builder API Pattern

Use the MarkdownBuilder for programmatic content creation:

# Builder pattern with callback
await page.append_markdown(lambda builder: (
    builder
    .heading("Welcome to Notionary", level=1)
    .callout("This is important information", emoji="💡")
    .heading("Features", level=2)
    .bulleted_list([
        "Easy to use",
        "Powerful API",
        "Great documentation"
    ])
))

Both approaches produce identical results, choose what fits your workflow best.

Advanced Layout Examples

For more complex structured content like multi-column layouts, you can use both approaches:

Direct Markdown Syntax:

await page.append_markdown("""
::: columns
::: column
## Getting Started
Follow these steps to begin:
1. Install the package
2. Set up authentication
3. Create your first page
:::

::: column
## Quick Tips
[callout](Pro tip: Use environment variables for API keys "💡")

- Start with simple examples
- Check the documentation
:::
:::
""")

Builder API Pattern:

await page.append_markdown(lambda builder: (
    builder.heading("Documentation Overview", level=1)
    .columns(
        # Left column - main content
        lambda col: (
            col.heading("Getting Started", level=2)
            .paragraph("Follow these steps to begin:")
            .numbered_list([
                "Install the package",
                "Set up authentication",
                "Create your first page"
            ])
        ),
        # Right column - sidebar
        lambda col: (
            col.heading("Quick Tips", level=2)
            .callout("Pro tip: Use environment variables for API keys", "💡")
            .bulleted_list([
                "Start with simple examples",
                "Check the documentation"
            ])
        ),
        width_ratios=[0.6, 0.4]  # 60% left, 40% right
    )
))

Complete Block Support

Notionary supports all official Notion block types as documented in the Notion API Reference.

Block Categories

Text Blocks

Text-based content blocks for writing and formatting.

  • Paragraph - Basic text content
  • Heading - H1, H2, H3 headings
  • Quote - Quoted text blocks
  • Callout - Highlighted information boxes
  • Code - Syntax-highlighted code blocks

List Blocks

Structured list content for organization.

Interactive Blocks

Blocks that provide interactive functionality.

Layout Blocks

Blocks for structuring page layout and organization.

  • Divider - Horizontal dividing lines
  • Column - Multi-column layouts and individual columns
  • Table - Structured data tables

Files & Media

Rich content integration and file handling.

  • Image - Image embeds and uploads
  • Video - Video embeds (YouTube, Vimeo, etc.)
  • PDF - PDF document embeds
  • File - File attachments and downloads
  • Embed - Generic web content embeds

Mathematical Blocks

Scientific and mathematical content.

  • Equation - LaTeX mathematical expressions

Page navigation and structure.

Content Creation Examples

Markdown Syntax Approach

# Using direct markdown strings
content = """
[toc]

## Overview
This project provides **powerful features** for developers.

[callout](💡 **Tip:** Check our examples for best practices "💡")

## Features
- Real-time collaboration
- Advanced analytics
- Custom integrations

## Code Example
```python
from notionary import NotionPage
page = await NotionPage.from_title("My Page")

Error Handling & Reliability

Notionary provides robust error handling for all content operations:

  • Text Length Validation - Automatic truncation for API limits
  • Graceful Fallbacks - Unsupported blocks convert to paragraphs
  • Retry Logic - Automatic retries for network issues
  • Content Validation - Ensures all blocks meet Notion requirements

Block Reference

Explore the complete documentation for each block type:

Text & Formatting: Paragraph • Heading • Quote • Callout • Code

Lists & Structure: Bulleted List • Numbered List

Layout & Organization: Divider • Column • Toggle • Table

Files & Media: Image • Video • PDF • File • Embed

Math & Navigation: Equation • Table of Contents • Breadcrumb

Next Steps