notionary 0.2.19__py3-none-any.whl → 0.2.22__py3-none-any.whl

notionary/__init__.py

@@ -1,9 +1,13 @@
-from .database import NotionDatabase, DatabaseFilterBuilder
+from notionary.blocks import bootstrap_blocks
+
+bootstrap_blocks()
+
+from .database import DatabaseFilterBuilder, NotionDatabase
+from .file_upload import NotionFileUpload
+from .markdown.markdown_builder import MarkdownBuilder
 from .page.notion_page import NotionPage
+from .user import NotionBotUser, NotionUser, NotionUserManager
 from .workspace import NotionWorkspace
-from .user import NotionUser, NotionUserManager, NotionBotUser
-from .file_upload import NotionFileUpload
-from .blocks.markdown_builder import MarkdownBuilder
 
 __all__ = [
     "NotionDatabase",

notionary/base_notion_client.py

@@ -2,9 +2,11 @@ import asyncio
 import os
 from abc import ABC
 from enum import Enum
-from typing import Dict, Any, Optional, Union
+from typing import Any, Dict, Optional, Union
+
 import httpx
 from dotenv import load_dotenv
+
 from notionary.util import LoggingMixin
 
 load_dotenv()

notionary/blocks/__init__.py

@@ -1,92 +1,3 @@
-# Order is important here, as some imports depend on others.
-from .prompts.element_prompt_content import ElementPromptContent
-from .prompts.element_prompt_builder import ElementPromptBuilder
+from ._bootstrap import bootstrap_blocks
 
-from .shared.notion_block_element import (
-    NotionBlockElement,
-    NotionBlockResult,
-    NotionBlock,
-)
-
-from .audio import AudioElement, AudioMarkdownNode
-from .bulleted_list import BulletedListElement, BulletedListMarkdownNode
-from .callout import CalloutElement, CalloutMarkdownNode
-from .code import CodeElement, CodeMarkdownNode
-from .column.column_element import ColumnElement
-from .divider import DividerElement, DividerMarkdownNode
-from .embed import EmbedElement, EmbedMarkdownNode
-from .heading import HeadingElement, HeadingMarkdownNode
-from .image import ImageElement, ImageMarkdownNode
-from .numbered_list import NumberedListElement, NumberedListMarkdownNode
-from .paragraph import ParagraphElement, ParagraphMarkdownNode
-from .table import TableElement, TableMarkdownNode
-from .toggle import ToggleElement, ToggleMarkdownNode
-from .todo import TodoElement, TodoMarkdownNode
-from .video import VideoElement, VideoMarkdownNode
-from .toggleable_heading import ToggleableHeadingElement, ToggleableHeadingMarkdownNode
-from .bookmark import BookmarkElement, BookmarkMarkdownNode
-from .divider import DividerElement, DividerMarkdownNode
-from .heading import HeadingElement, HeadingMarkdownNode
-from .mention import MentionElement, MentionMarkdownNode
-from .quote import QuoteElement, QuoteMarkdownNode
-from .document import DocumentElement, DocumentMarkdownNode
-from .shared.text_inline_formatter import TextInlineFormatter
-
-from .markdown_node import MarkdownNode
-
-from .registry.block_registry import BlockRegistry
-from .registry.block_registry_builder import BlockRegistryBuilder
-
-from .shared.block_client import NotionBlockClient
-
-__all__ = [
-    "MarkdownNode",
-    "ElementPromptContent",
-    "ElementPromptBuilder",
-    "NotionBlockElement",
-    "AudioElement",
-    "AudioMarkdownNode",
-    "BulletedListElement",
-    "BulletedListMarkdownNode",
-    "CalloutElement",
-    "CalloutMarkdownNode",
-    "CodeElement",
-    "CodeMarkdownNode",
-    "ColumnElement",
-    "DividerElement",
-    "DividerMarkdownNode",
-    "EmbedElement",
-    "EmbedMarkdownNode",
-    "HeadingElement",
-    "HeadingMarkdownNode",
-    "ImageElement",
-    "ImageMarkdownNode",
-    "NumberedListElement",
-    "NumberedListMarkdownNode",
-    "ParagraphElement",
-    "ParagraphMarkdownNode",
-    "TableElement",
-    "TableMarkdownNode",
-    "ToggleElement",
-    "ToggleMarkdownNode",
-    "TodoElement",
-    "TodoMarkdownNode",
-    "VideoElement",
-    "VideoMarkdownNode",
-    "ToggleableHeadingElement",
-    "ToggleableHeadingMarkdownNode",
-    "BookmarkElement",
-    "BookmarkMarkdownNode",
-    "MentionElement",
-    "MentionMarkdownNode",
-    "QuoteElement",
-    "QuoteMarkdownNode",
-    "DocumentElement",
-    "DocumentMarkdownNode",
-    "BlockRegistry",
-    "BlockRegistryBuilder",
-    "TextInlineFormatter",
-    "NotionBlockResult",
-    "NotionBlock",
-    "NotionBlockClient",
-]
+__all__ = ["bootstrap_blocks"]

notionary/blocks/_bootstrap.py

@@ -0,0 +1,271 @@
+from __future__ import annotations
+
+from typing import Optional, Union
+
+_bootstrapped = False
+
+
+def bootstrap_blocks() -> None:
+    global _bootstrapped
+    if _bootstrapped:
+        return
+
+    from notionary.blocks import (
+        bookmark,
+        breadcrumbs,
+        bulleted_list,
+        callout,
+        child_page,
+        code,
+        column,
+        divider,
+        embed,
+        equation,
+        file,
+        heading,
+        image_block,
+        models,
+        numbered_list,
+        paragraph,
+        quote,
+        table,
+        table_of_contents,
+        todo,
+        toggle,
+        toggleable_heading,
+        video,
+        child_database,
+    )
+
+    # Collect all exports from modules
+    ns = {}
+    for m in (
+        bookmark,
+        breadcrumbs,
+        bulleted_list,
+        callout,
+        child_page,
+        code,
+        column,
+        divider,
+        embed,
+        equation,
+        file,
+        heading,
+        image_block,
+        numbered_list,
+        paragraph,
+        quote,
+        table,
+        todo,
+        toggle,
+        video,
+        toggleable_heading,
+        table_of_contents,
+        child_database,
+    ):
+        ns.update(vars(m))
+
+    # Add missing types that are needed for model rebuilding
+    # These are the types that are only defined in TYPE_CHECKING in block_models
+    from notionary.blocks.bookmark.bookmark_models import (
+        BookmarkBlock,
+        CreateBookmarkBlock,
+    )
+    from notionary.blocks.breadcrumbs.breadcrumb_models import (
+        BreadcrumbBlock,
+        CreateBreadcrumbBlock,
+    )
+    from notionary.blocks.bulleted_list.bulleted_list_models import (
+        BulletedListItemBlock,
+        CreateBulletedListItemBlock,
+    )
+    from notionary.blocks.callout.callout_models import CalloutBlock, CreateCalloutBlock
+    from notionary.blocks.child_page.child_page_models import (
+        ChildPageBlock,
+        CreateChildPageBlock,
+    )
+    from notionary.blocks.code.code_models import CodeBlock, CreateCodeBlock
+    from notionary.blocks.column.column_models import (
+        ColumnBlock,
+        ColumnListBlock,
+        CreateColumnBlock,
+        CreateColumnListBlock,
+    )
+    from notionary.blocks.divider.divider_models import CreateDividerBlock, DividerBlock
+    from notionary.blocks.embed.embed_models import CreateEmbedBlock, EmbedBlock
+    from notionary.blocks.equation.equation_models import (
+        CreateEquationBlock,
+        EquationBlock,
+    )
+    from notionary.blocks.file.file_element_models import CreateFileBlock, FileBlock
+    from notionary.blocks.heading.heading_models import (
+        CreateHeading1Block,
+        CreateHeading2Block,
+        CreateHeading3Block,
+        HeadingBlock,
+    )
+    from notionary.blocks.image_block.image_models import CreateImageBlock
+    from notionary.blocks.numbered_list.numbered_list_models import (
+        CreateNumberedListItemBlock,
+        NumberedListItemBlock,
+    )
+    from notionary.blocks.paragraph.paragraph_models import (
+        CreateParagraphBlock,
+        ParagraphBlock,
+    )
+    from notionary.blocks.pdf.pdf_models import CreatePdfBlock
+    from notionary.blocks.quote.quote_models import CreateQuoteBlock, QuoteBlock
+    from notionary.blocks.table.table_models import TableBlock, TableRowBlock
+    from notionary.blocks.table_of_contents.table_of_contents_models import (
+        CreateTableOfContentsBlock,
+        TableOfContentsBlock,
+    )
+    from notionary.blocks.todo.todo_models import CreateToDoBlock, ToDoBlock
+    from notionary.blocks.toggle.toggle_models import CreateToggleBlock, ToggleBlock
+    from notionary.blocks.types import BlockType
+    from notionary.blocks.video.video_element_models import CreateVideoBlock
+    from notionary.blocks.child_database.child_database_models import (
+        CreateChildDatabaseBlock,
+        ChildDatabaseBlock,
+    )
+
+    # Define the Union types that are needed for model rebuilding
+    BlockCreateRequest = Union[
+        CreateBookmarkBlock,
+        CreateBreadcrumbBlock,
+        CreateBulletedListItemBlock,
+        CreateCalloutBlock,
+        CreateChildPageBlock,
+        CreateCodeBlock,
+        CreateColumnListBlock,
+        CreateColumnBlock,
+        CreateDividerBlock,
+        CreateEmbedBlock,
+        CreateEquationBlock,
+        CreateFileBlock,
+        CreateHeading1Block,
+        CreateHeading2Block,
+        CreateHeading3Block,
+        CreateImageBlock,
+        CreateNumberedListItemBlock,
+        CreateParagraphBlock,
+        CreateQuoteBlock,
+        CreateToDoBlock,
+        CreateToggleBlock,
+        CreateVideoBlock,
+        CreateTableOfContentsBlock,
+        CreatePdfBlock,
+        CreateChildDatabaseBlock,
+    ]
+
+    BlockCreateResult = Optional[BlockCreateRequest]
+
+    # Add all block types to namespace
+    ns.update(
+        {
+            "BlockType": BlockType,
+            "BookmarkBlock": BookmarkBlock,
+            "CreateBookmarkBlock": CreateBookmarkBlock,
+            "BreadcrumbBlock": BreadcrumbBlock,
+            "CreateBreadcrumbBlock": CreateBreadcrumbBlock,
+            "BulletedListItemBlock": BulletedListItemBlock,
+            "CreateBulletedListItemBlock": CreateBulletedListItemBlock,
+            "CalloutBlock": CalloutBlock,
+            "CreateCalloutBlock": CreateCalloutBlock,
+            "ChildPageBlock": ChildPageBlock,
+            "CreateChildPageBlock": CreateChildPageBlock,
+            "CodeBlock": CodeBlock,
+            "CreateCodeBlock": CreateCodeBlock,
+            "ColumnBlock": ColumnBlock,
+            "ColumnListBlock": ColumnListBlock,
+            "CreateColumnBlock": CreateColumnBlock,
+            "CreateColumnListBlock": CreateColumnListBlock,
+            "DividerBlock": DividerBlock,
+            "CreateDividerBlock": CreateDividerBlock,
+            "EmbedBlock": EmbedBlock,
+            "CreateEmbedBlock": CreateEmbedBlock,
+            "EquationBlock": EquationBlock,
+            "CreateEquationBlock": CreateEquationBlock,
+            "FileBlock": FileBlock,
+            "CreateFileBlock": CreateFileBlock,
+            "HeadingBlock": HeadingBlock,
+            "CreateHeading1Block": CreateHeading1Block,
+            "CreateHeading2Block": CreateHeading2Block,
+            "CreateHeading3Block": CreateHeading3Block,
+            "CreateImageBlock": CreateImageBlock,
+            "NumberedListItemBlock": NumberedListItemBlock,
+            "CreateNumberedListItemBlock": CreateNumberedListItemBlock,
+            "ParagraphBlock": ParagraphBlock,
+            "CreateParagraphBlock": CreateParagraphBlock,
+            "QuoteBlock": QuoteBlock,
+            "CreateQuoteBlock": CreateQuoteBlock,
+            "TableBlock": TableBlock,
+            "TableRowBlock": TableRowBlock,
+            "ToDoBlock": ToDoBlock,
+            "CreateToDoBlock": CreateToDoBlock,
+            "ToggleBlock": ToggleBlock,
+            "CreateToggleBlock": CreateToggleBlock,
+            "CreateVideoBlock": CreateVideoBlock,
+            "TableOfContentsBlock": TableOfContentsBlock,
+            "CreateTableOfContentsBlock": CreateTableOfContentsBlock,
+            "ChildDatabaseBlock": ChildDatabaseBlock,
+            # Add the Union types
+            "BlockCreateRequest": BlockCreateRequest,
+            "BlockCreateResult": BlockCreateResult,
+        }
+    )
+
+    # Now rebuild with complete namespace
+    models.Block.model_rebuild(_types_namespace=ns)
+    models.BlockChildrenResponse.model_rebuild(_types_namespace=ns)
+
+    # Rebuild all individual block models
+    BookmarkBlock.model_rebuild()
+    BreadcrumbBlock.model_rebuild()
+    BulletedListItemBlock.model_rebuild()
+    CalloutBlock.model_rebuild()
+    ChildPageBlock.model_rebuild()
+    CodeBlock.model_rebuild()
+    ColumnBlock.model_rebuild()
+    ColumnListBlock.model_rebuild()
+    DividerBlock.model_rebuild()
+    EmbedBlock.model_rebuild()
+    EquationBlock.model_rebuild()
+    FileBlock.model_rebuild()
+    HeadingBlock.model_rebuild()
+    NumberedListItemBlock.model_rebuild()
+    ParagraphBlock.model_rebuild()
+    QuoteBlock.model_rebuild()
+    TableBlock.model_rebuild()
+    TableRowBlock.model_rebuild()
+    ToDoBlock.model_rebuild()
+    ToggleBlock.model_rebuild()
+    TableOfContentsBlock.model_rebuild()
+
+    # Rebuild create models
+    CreateBookmarkBlock.model_rebuild()
+    CreateBreadcrumbBlock.model_rebuild()
+    CreateBulletedListItemBlock.model_rebuild()
+    CreateCalloutBlock.model_rebuild()
+    CreateChildPageBlock.model_rebuild()
+    CreateCodeBlock.model_rebuild()
+    CreateColumnListBlock.model_rebuild()
+    CreateColumnBlock.model_rebuild()
+    CreateDividerBlock.model_rebuild()
+    CreateEmbedBlock.model_rebuild()
+    CreateEquationBlock.model_rebuild()
+    CreateFileBlock.model_rebuild()
+    CreateHeading1Block.model_rebuild()
+    CreateHeading2Block.model_rebuild()
+    CreateHeading3Block.model_rebuild()
+    CreateImageBlock.model_rebuild()
+    CreateNumberedListItemBlock.model_rebuild()
+    CreateParagraphBlock.model_rebuild()
+    CreateQuoteBlock.model_rebuild()
+    CreateToDoBlock.model_rebuild()
+    CreateToggleBlock.model_rebuild()
+    CreateVideoBlock.model_rebuild()
+    CreateTableOfContentsBlock.model_rebuild()
+
+    _bootstrapped = True

notionary/blocks/audio/__init__.py

@@ -1,7 +1,13 @@
-from .audio_element import AudioElement
-from .audio_markdown_node import AudioMarkdownNode
+from notionary.blocks.audio.audio_element import AudioElement
+from notionary.blocks.audio.audio_markdown_node import (
+    AudioMarkdownBlockParams,
+    AudioMarkdownNode,
+)
+from notionary.blocks.audio.audio_models import CreateAudioBlock
 
 __all__ = [
     "AudioElement",
+    "CreateAudioBlock",
     "AudioMarkdownNode",
+    "AudioMarkdownBlockParams",
 ]

notionary/blocks/audio/audio_element.py

@@ -1,152 +1,115 @@
+from __future__ import annotations
+
 import re
-from typing import Any, Optional, List
+from typing import Optional
 
-from notionary.blocks import (
-    NotionBlockElement,
-    ElementPromptContent,
-    ElementPromptBuilder,
-    NotionBlockResult,
-)
-from notionary.blocks.shared.models import RichTextObject
+from notionary.blocks.audio.audio_models import CreateAudioBlock
+from notionary.blocks.base_block_element import BaseBlockElement
+from notionary.blocks.file.file_element_models import ExternalFile, FileBlock, FileType
+from notionary.blocks.mixins.captions import CaptionMixin
+from notionary.blocks.syntax_prompt_builder import BlockElementMarkdownInformation
+from notionary.blocks.models import Block, BlockCreateResult, BlockType
 
 
-class AudioElement(NotionBlockElement):
+class AudioElement(BaseBlockElement, CaptionMixin):
     """
     Handles conversion between Markdown audio embeds and Notion audio blocks.
 
     Markdown audio syntax:
     - [audio](https://example.com/audio.mp3) - Simple audio embed
-    - [audio](https://example.com/audio.mp3 "Caption text") - Audio with caption
+    - [audio](https://example.com/audio.mp3)(caption:Episode 1) - Audio with caption
+    - (caption:Background music)[audio](https://example.com/song.mp3) - caption before URL
 
     Where:
     - URL is the required audio file URL
-    - Caption is optional descriptive text (enclosed in quotes)
+    - Caption supports rich text formatting and is optional
     """
 
-    # Regex patterns
-    URL_PATTERN = r"(https?://[^\s\"]+)"
-    CAPTION_PATTERN = r'(?:\s+"([^"]+)")?'
+    # Simple pattern that matches just the audio link, CaptionMixin handles caption separately
+    AUDIO_PATTERN = re.compile(r"\[audio\]\((https?://[^\s\"]+)\)")
 
-    PATTERN = re.compile(r"^\[audio\]\(" + URL_PATTERN + CAPTION_PATTERN + r"\)$")
+    @classmethod
+    def _extract_audio_url(cls, text: str) -> Optional[str]:
+        """Extract audio URL from text, handling caption patterns."""
+        # First remove any captions to get clean text for URL extraction
+        clean_text = cls.remove_caption(text)
 
-    # Supported audio extensions
-    SUPPORTED_EXTENSIONS = {".mp3", ".wav", ".ogg", ".oga", ".m4a"}
+        # Now extract the URL from clean text
+        match = cls.AUDIO_PATTERN.search(clean_text)
+        if match:
+            return match.group(1)
 
-    @classmethod
-    def match_markdown(cls, text: str) -> bool:
-        m = cls.PATTERN.match(text.strip())
-        if not m:
-            return False
-        url = m.group(1)
-        return cls._is_likely_audio_url(url)
+        return None
+
+    SUPPORTED_EXTENSIONS = {".mp3", ".wav", ".ogg", ".oga", ".m4a"}
 
     @classmethod
-    def match_notion(cls, block: dict[str, Any]) -> bool:
-        """Check if block is a Notion audio block."""
-        return block.get("type") == "audio"
+    def match_notion(cls, block: Block) -> bool:
+        """Check if this element can handle the given Notion block."""
+        return block.type == BlockType.AUDIO
 
     @classmethod
-    def markdown_to_notion(cls, text: str) -> NotionBlockResult:
+    async def markdown_to_notion(cls, text: str) -> BlockCreateResult:
         """Convert markdown audio embed to Notion audio block."""
-        audio_match = cls.PATTERN.match(text.strip())
-        if not audio_match:
-            return None
-
-        url = audio_match.group(1)
-        caption_text = audio_match.group(2)
-
+        # Use our helper method to extract the URL
+        url = cls._extract_audio_url(text.strip())
         if not url:
             return None
 
-        # Validate URL if possible
         if not cls._is_likely_audio_url(url):
-            # Still proceed - user might know better
-            pass
+            return None
 
-        audio_data = {"type": "external", "external": {"url": url}}
+        # Use mixin to extract caption (if present anywhere in text)
+        caption_text = cls.extract_caption(text.strip())
+        caption_rich_text = cls.build_caption_rich_text(caption_text or "")
 
-        # Add caption if provided
-        if caption_text:
-            caption_rich_text = RichTextObject.from_plain_text(caption_text)
-            audio_data["caption"] = [caption_rich_text.model_dump()]
-        else:
-            audio_data["caption"] = []
+        audio_content = FileBlock(
+            type=FileType.EXTERNAL,
+            external=ExternalFile(url=url),
+            caption=caption_rich_text,
+        )
 
-        return {"type": "audio", "audio": audio_data}
+        return CreateAudioBlock(audio=audio_content)
 
     @classmethod
-    def notion_to_markdown(cls, block: dict[str, Any]) -> Optional[str]:
+    async def notion_to_markdown(cls, block: Block) -> Optional[str]:
         """Convert Notion audio block to markdown audio embed."""
-        if block.get("type") != "audio":
+        if block.type != BlockType.AUDIO or block.audio is None:
             return None
 
-        audio_data = block.get("audio", {})
+        audio = block.audio
 
-        # Get URL from external source
-        if audio_data.get("type") == "external":
-            url = audio_data.get("external", {}).get("url", "")
-        else:
-            # Handle file or file_upload types if needed
+        # Only handle external audio
+        if audio.type != FileType.EXTERNAL or audio.external is None:
             return None
-
+        url = audio.external.url
         if not url:
             return None
 
-        # Extract caption
-        caption = audio_data.get("caption", [])
-        if caption:
-            caption_text = cls._extract_text_content(caption)
-            return f'[audio]({url} "{caption_text}")'
+        result = f"[audio]({url})"
+
+        # Add caption if present
+        caption_markdown = await cls.format_caption_for_markdown(audio.caption or [])
+        if caption_markdown:
+            result += caption_markdown
 
-        return f"[audio]({url})"
+        return result
 
     @classmethod
-    def is_multiline(cls) -> bool:
-        """Audio embeds are single-line elements."""
-        return False
+    def get_system_prompt_information(cls) -> Optional[BlockElementMarkdownInformation]:
+        """Get system prompt information for audio blocks."""
+        return BlockElementMarkdownInformation(
+            block_type=cls.__name__,
+            description="Audio blocks embed audio files from external URLs with optional captions",
+            syntax_examples=[
+                "[audio](https://example.com/song.mp3)",
+                "[audio](https://example.com/podcast.wav)(caption:Episode 1)",
+                "(caption:Background music)[audio](https://soundcloud.com/track/123)",
+                "[audio](https://example.com/interview.mp3)(caption:**Live** interview)",
+            ],
+            usage_guidelines="Use for embedding audio files like music, podcasts, or sound effects. Supports common audio formats (mp3, wav, ogg, m4a). Caption supports rich text formatting and is optional.",
+        )
 
     @classmethod
     def _is_likely_audio_url(cls, url: str) -> bool:
-        """Check if URL likely points to an audio file."""
         return any(url.lower().endswith(ext) for ext in cls.SUPPORTED_EXTENSIONS)
-
-    @classmethod
-    def _extract_text_content(cls, rich_text: List[dict[str, Any]]) -> str:
-        """Extract plain text content from Notion rich_text elements."""
-        result = ""
-        for text_obj in rich_text:
-            if text_obj.get("type") == "text":
-                result += text_obj.get("text", {}).get("content", "")
-            elif "plain_text" in text_obj:
-                result += text_obj.get("plain_text", "")
-        return result
-
-    @classmethod
-    def get_llm_prompt_content(cls) -> ElementPromptContent:
-        """
-        Returns structured LLM prompt metadata for the audio element.
-        """
-        return (
-            ElementPromptBuilder()
-            .with_description(
-                "Embeds an audio file that can be played directly in the page."
-            )
-            .with_usage_guidelines(
-                "Use audio embeds when you want to include sound files, music, podcasts, "
-                "or voice recordings. Supports common audio formats like MP3, WAV, OGG, and M4A."
-            )
-            .with_syntax('![audio](https://example.com/audio.mp3 "Optional caption")')
-            .with_examples(
-                [
-                    "[audio](https://example.com/song.mp3)",
-                    '[audio](https://example.com/podcast.mp3 "Episode 1: Introduction")',
-                    '[audio](https://example.com/sound.wav "Sound effect for presentation")',
-                    '[audio](https://example.com/recording.m4a "Voice memo from meeting")',
-                ]
-            )
-            .with_avoidance_guidelines(
-                "Ensure the URL points to a valid audio file. "
-                "Some audio formats may not be supported by all browsers."
-            )
-            .build()
-        )

notionary/blocks/audio/audio_markdown_node.py

@@ -1,8 +1,11 @@
 from __future__ import annotations
+
 from typing import Optional
+
 from pydantic import BaseModel
 
-from notionary.blocks.markdown_node import MarkdownNode
+from notionary.markdown.markdown_node import MarkdownNode
+from notionary.blocks.mixins.captions import CaptionMarkdownNodeMixin
 
 
 class AudioMarkdownBlockParams(BaseModel):
@@ -10,7 +13,7 @@ class AudioMarkdownBlockParams(BaseModel):
     caption: Optional[str] = None
 
 
-class AudioMarkdownNode(MarkdownNode):
+class AudioMarkdownNode(MarkdownNode, CaptionMarkdownNodeMixin):
     """
     Programmatic interface for creating Notion-style audio blocks.
     """
@@ -24,6 +27,11 @@ class AudioMarkdownNode(MarkdownNode):
         return cls(url=params.url, caption=params.caption)
 
     def to_markdown(self) -> str:
-        if self.caption:
-            return f'[audio]({self.url} "{self.caption}")'
-        return f"[audio]({self.url})"
+        """Return the Markdown representation.
+
+        Examples:
+        - [audio](https://example.com/song.mp3)
+        - [audio](https://example.com/song.mp3)(caption:Background music)
+        """
+        base_markdown = f"[audio]({self.url})"
+        return self.append_caption_to_markdown(base_markdown, self.caption)