INSTALL duck_block_utils FROM community;
LOAD duck_block_utils;

-- Build a document programmatically
SELECT db_assemble([
    db_heading(1, 'Hello World'),
    db_paragraph([
        db_text('This is '),
        db_bold('important'),
        db_text(' content.')
    ]),
    db_code('sql', 'SELECT * FROM documents')
]);

-- Works with markdown extension for reading/writing files
LOAD markdown;
LOAD duck_block_utils;

-- Extract table of contents from markdown
SELECT * FROM db_blocks_toc(
    (SELECT list(b) FROM read_markdown_blocks('README.md') b)
);

-- Convert blocks to plain text
SELECT db_blocks_to_text(
    (SELECT list(b) FROM read_markdown_blocks('doc.md') b)
);

-- Validate document structure
SELECT db_blocks_validate(
    (SELECT list(b) FROM read_markdown_blocks('doc.md') b)
);

STRUCT(
    kind VARCHAR,                       -- 'block' or 'inline'
    element_type VARCHAR,               -- 'heading', 'paragraph', 'bold', 'link', etc.
    content VARCHAR,                    -- Text content (NULL if element has children)
    level INTEGER,                      -- Structural depth (1=block, 2+=inline children)
    encoding VARCHAR,                   -- 'text', 'json', 'html', etc.
    attributes MAP(VARCHAR, VARCHAR),   -- Element-specific metadata
    element_order INTEGER               -- Position in document
)

-- Builders can be nested naturally
SELECT db_paragraph([
    db_text('Click '),
    db_link('https://example.com', 'here'),
    db_text(' for more.')
]);

-- Read markdown, manipulate with duck_block_utils, write back
LOAD markdown;
LOAD duck_block_utils;

-- Add a disclaimer to all documents
COPY (
    SELECT block.* FROM (
        SELECT unnest(db_assemble([
            (SELECT list(b) FROM read_markdown_blocks('doc.md') b),
            db_hr(),
            db_paragraph('Generated by DuckDB')
        ])) as block
    )
) TO 'output.md' (FORMAT markdown, MARKDOWN_MODE duck_block);