BlockNote Python Library - Complete Guide¶

What is BlockNote-py?¶

BlockNote-py is the official Python library for BlockNote.js, providing comprehensive support for working with BlockNote blocks in Python applications. Whether you're building a Python backend, processing content server-side, or need to convert between different formats, BlockNote-py makes it simple and type-safe.

Key Features for Python Developers¶

🐍 Native Python Integration¶

Pure Python implementation - No JavaScript dependencies
Type-safe operations - Built with Pydantic for robust validation
Pythonic API - Follows Python conventions and best practices
Cross-platform support - Works on Windows, macOS, and Linux

🔄 Format Conversion¶

BlockNote to HTML - Server-side rendering for SEO
BlockNote to Markdown - Export to documentation formats
BlockNote to JSON/Dict - Database storage and API responses
HTML to BlockNote - Import existing content
Markdown to BlockNote - Convert documentation to rich blocks

🚀 Performance & Reliability¶

Fast conversion - Optimized for production use
Memory efficient - Handles large documents
Well tested - 70+ comprehensive tests
Production ready - Used in real-world applications

Common Use Cases¶

1. Python Web Applications¶

from blocknote.converter import blocks_to_html
from django.http import HttpResponse

def render_content(request, content_blocks):
    html = blocks_to_html(content_blocks)
    return HttpResponse(html)

2. Content Management Systems¶

from blocknote.converter import html_to_blocks, blocks_to_dict

# Import existing HTML content
blocks = html_to_blocks(existing_html)

# Store in database as JSON
content_json = blocks_to_dict(blocks)

3. API Development¶

from fastapi import FastAPI
from blocknote.converter import blocks_to_html

app = FastAPI()

@app.post("/render")
async def render_blocks(blocks: list):
    return {"html": blocks_to_html(blocks)}

4. Documentation Processing¶

from blocknote.converter import blocks_to_markdown

# Convert BlockNote content to Markdown for docs
markdown_content = blocks_to_markdown(blocks)

Installation & Setup¶

Quick Installation¶

pip install blocknote-py

Development Installation¶

git clone https://github.com/rohansharmasitoula/blocknote-py.git
cd blocknote-py
pip install -e .

Verify Installation¶

import blocknote
print(blocknote.__version__)

Python Version Support¶

BlockNote-py supports Python 3.8+ with full compatibility across:

Python 3.8 - Minimum supported version
Python 3.9 - Full feature support
Python 3.10 - Recommended for new projects
Python 3.11 - Latest features and performance
Python 3.12 - Cutting-edge Python support
Python 3.13 - Future-ready compatibility

Framework Integration¶

Django Integration¶

# models.py
from django.db import models
from blocknote.converter import blocks_to_html, html_to_blocks

class Article(models.Model):
    content_blocks = models.JSONField()

    def get_html(self):
        return blocks_to_html(self.content_blocks)

    def set_from_html(self, html):
        self.content_blocks = html_to_blocks(html)

Flask Integration¶

from flask import Flask, render_template_string
from blocknote.converter import blocks_to_html

app = Flask(__name__)

@app.route('/article/<int:id>')
def show_article(id):
    blocks = get_article_blocks(id)  # Your data source
    html_content = blocks_to_html(blocks)
    return render_template_string('<div>{{ content|safe }}</div>', 
                                content=html_content)

FastAPI Integration¶

from fastapi import FastAPI
from pydantic import BaseModel
from blocknote.converter import blocks_to_html, html_to_blocks

app = FastAPI()

class ContentRequest(BaseModel):
    blocks: list

@app.post("/convert/html")
async def convert_to_html(request: ContentRequest):
    html = blocks_to_html(request.blocks)
    return {"html": html}

Advanced Features¶

Custom Block Types¶

from blocknote.schema import Block, InlineContent

# Create custom blocks
custom_block = Block(
    id="custom-1",
    type="callout",
    props={"type": "warning"},
    content=[
        InlineContent(
            type="text",
            text="Important notice",
            styles={"bold": True}
        )
    ]
)

Batch Processing¶

from blocknote.converter import blocks_to_html

# Process multiple documents
documents = [doc1_blocks, doc2_blocks, doc3_blocks]
html_outputs = [blocks_to_html(doc) for doc in documents]

Error Handling¶

from blocknote.converter import blocks_to_html
from pydantic import ValidationError

try:
    html = blocks_to_html(blocks)
except ValidationError as e:
    print(f"Invalid block structure: {e}")
except Exception as e:
    print(f"Conversion error: {e}")

Performance Tips¶

1. Batch Operations¶

Process multiple blocks together for better performance:

# Good: Process all blocks at once
html = blocks_to_html(all_blocks)

# Avoid: Processing blocks individually
html_parts = [blocks_to_html([block]) for block in all_blocks]

2. Caching Results¶

Cache converted content for frequently accessed data:

from functools import lru_cache

@lru_cache(maxsize=128)
def cached_blocks_to_html(blocks_json):
    blocks = json.loads(blocks_json)
    return blocks_to_html(blocks)

3. Memory Management¶

For large documents, process in chunks:

def process_large_document(blocks, chunk_size=100):
    for i in range(0, len(blocks), chunk_size):
        chunk = blocks[i:i + chunk_size]
        yield blocks_to_html(chunk)

SEO Benefits¶

Server-Side Rendering¶

BlockNote-py enables server-side rendering of BlockNote content, providing:

Better SEO - Search engines can crawl your content
Faster loading - Pre-rendered HTML loads instantly
Social sharing - Rich previews with proper meta tags
Accessibility - Screen readers can parse the content

Example SEO Implementation¶

from blocknote.converter import blocks_to_html
from django.shortcuts import render

def article_view(request, slug):
    article = get_article(slug)
    html_content = blocks_to_html(article.blocks)

    context = {
        'title': article.title,
        'content': html_content,
        'meta_description': extract_text_preview(article.blocks)
    }
    return render(request, 'article.html', context)

Community & Support¶

Getting Help¶

☕ Support Development¶

If BlockNote-py has helped your project, consider supporting its continued development:

Your support enables: - 🚀 New features - Adding more conversion formats and capabilities - 🐛 Bug fixes - Maintaining high quality and reliability - 📚 Documentation - Keeping guides and examples up-to-date - 🧪 Testing - Ensuring compatibility across Python versions - 💬 Community support - Helping users and answering questions

Contributing¶

We welcome contributions! See our Contributing Guide for details on: - Setting up development environment - Running tests - Submitting pull requests - Code style guidelines

BlockNote.js - The original JavaScript library
Pydantic - Data validation library we use
Markdown-it-py - Markdown processing

Conclusion¶

BlockNote-py brings the power of BlockNote.js to the Python ecosystem, enabling developers to build robust, type-safe applications that work with rich text content. Whether you're building a CMS, API, or web application, BlockNote-py provides the tools you need to handle BlockNote content effectively in Python.

Start building with BlockNote-py today and join the growing community of Python developers using BlockNote for their rich text processing needs!