Add to Changelog

BlockDoc

A simple, powerful standard for structured content that works beautifully with LLMs, humans, and modern editors.

[](https://pypi.org/project/blockdoc/) [](https://pypi.org/project/blockdoc/) [](https://opensource.org/licenses/MIT)

Why BlockDoc?

BlockDoc provides a lightweight, flexible format for structured content that is:

• LLM-friendly: Optimized for AI generation and targeted modifications
• Simple: Flat structure with semantic IDs and minimal nesting
• Extensible: Core block types with room for custom extensions
• Framework-agnostic: Works with any frontend or backend technology
• Database-ready: Easy to store and query in SQL or NoSQL databases

Core Concepts

BlockDoc is based on a block-based architecture where content is organized into discrete, individually addressable blocks. Each block has:

• A semantic ID (like 'intro', 'section-1')
• A block type ('text', 'heading', 'image', 'code')
• Content (in Markdown for text-based blocks)
• Optional metadata

This architecture enables:

• Targeted updates to specific sections
• Better organization of content
• Easy integration with LLMs
• Flexible rendering in different formats

Core Block Types

1. Text - Standard paragraphs with Markdown support
2. Heading - Section headers with configurable levels
3. Image - Pictures with src, alt text, and optional caption
4. Code - Code blocks with syntax highlighting
5. List - Ordered or unordered lists
6. Quote - Blockquote content
7. Embed - Embedded content (videos, social media posts)
8. Divider - Horizontal rule/separator

Design Principles

1. Simplicity: Minimal structure with only necessary properties
2. LLM-Friendly: Optimized for AI content generation and modification
3. Human-Editable: Clear, readable format for direct editing
4. Database-Ready: Easily stored in SQL or NoSQL databases
5. Extensible: Core types with support for custom block types

...