Markdown Parser - Component Specification

docs/
├── index.md              # Document introduction (optional)
├── 01_introduction/
│   ├── index.md          # Chapter introduction (optional)
│   ├── 01_overview.md
│   └── 02_goals.md
├── 02_architecture/
│   ├── 01_constraints.md
│   └── 02_decisions.md
└── 03_appendix.md        # Single file as chapter

---
title: Document Title
author: John Doe
date: 2024-01-15
tags: [architecture, design]
custom_field: arbitrary value
---

# Heading

Content...

```python
def hello():
    print("Hello, World!")
```

| Header 1 | Header 2 |
|----------|----------|
| Cell 1   | Cell 2   |

![Alt Text](path/to/image.png "Optional Title")

@dataclass
class MarkdownDocument:
    """Represents a parsed Markdown document."""
    file_path: Path
    frontmatter: dict[str, Any]
    title: str
    sections: list[MarkdownSection]
    elements: list[MarkdownElement]

@dataclass
class MarkdownSection:
    """A section (heading) in the document."""
    title: str
    level: int                    # 1-6
    start_line: int
    end_line: int
    path: str                     # Hierarchical path
    children: list[MarkdownSection]

@dataclass
class MarkdownElement:
    """An extractable element (code, table, image)."""
    type: Literal["code", "table", "image"]
    start_line: int
    end_line: int
    attributes: dict[str, Any]    # Type-specific attributes
    parent_section: str           # Path of containing section

@dataclass
class FolderDocument:
    """A document from multiple Markdown files."""
    root_path: Path
    documents: list[MarkdownDocument]  # Sorted
    structure: DocumentStructure       # Combined hierarchy

Scenario: Headings are correctly extracted
  Given a Markdown file with the following content:
    """
    # Main Title

    ## Subchapter 1

    Text...

    ## Subchapter 2

    ### Sub-subchapter
    """
  When the parser processes the file
  Then 4 sections are extracted
  And the hierarchy is:
    | path                              | level |
    | /main-title                       | 1     |
    | /main-title/subchapter-1          | 2     |
    | /main-title/subchapter-2          | 2     |
    | /main-title/subchapter-2/sub-subchapter | 3 |

Scenario: YAML frontmatter is correctly parsed
  Given a Markdown file with the following content:
    """
    ---
    title: My Document
    author: John Doe
    tags: [design, architecture]
    ---

    # Content
    """
  When the parser processes the file
  Then frontmatter["title"] equals "My Document"
  And frontmatter["author"] equals "John Doe"
  And frontmatter["tags"] is a list with 2 elements

Scenario: Fenced code blocks are extracted
  Given a Markdown file with a Python code block
  When the parser processes the file
  Then elements contains an entry of type "code"
  And its language equals "python"
  And start_line and end_line are correctly set

Scenario: GFM tables are recognized as blocks
  Given a Markdown file with a 3-column table
  When the parser processes the file
  Then elements contains an entry of type "table"
  And columns equals 3

Scenario: Folder hierarchy is correctly mapped
  Given a folder with the following structure:
    | Path                    |
    | index.md                |
    | 01_intro/index.md       |
    | 01_intro/01_details.md  |
    | 02_chapter.md           |
  When the parser processes the folder
  Then the document order is:
    | index.md                |
    | 01_intro/index.md       |
    | 01_intro/01_details.md  |
    | 02_chapter.md           |

Scenario: Numeric prefixes are correctly sorted
  Given a folder with files: 10_z.md, 2_b.md, 1_a.md, README.md
  When the parser processes the folder
  Then the order is: README.md, 1_a.md, 2_b.md, 10_z.md

class MarkdownParser:
    """Parser for GitHub Flavored Markdown documents."""

    def parse_file(self, file_path: Path) -> MarkdownDocument:
        """Parses a single Markdown file."""
        ...

    def parse_folder(self, folder_path: Path) -> FolderDocument:
        """Parses a folder with Markdown files."""
        ...

    def get_section(self, doc: MarkdownDocument, path: str) -> MarkdownSection | None:
        """Finds a section by its hierarchical path."""
        ...

    def get_elements(
        self,
        doc: MarkdownDocument,
        element_type: str | None = None
    ) -> list[MarkdownElement]:
        """Returns all elements, optionally filtered by type."""
        ...

# ATX Heading
HEADING_PATTERN = r'^(#{1,6})\s+(.+?)(?:\s+#*)?$'

# Fenced Code Block (opening)
CODE_FENCE_OPEN = r'^(`{3,}|~{3,})(\w*)?$'

# YAML Frontmatter
FRONTMATTER_PATTERN = r'^---\s*\n(.*?)\n---\s*\n'

# Image
IMAGE_PATTERN = r'!\[([^\]]*)\]\(([^)\s]+)(?:\s+"([^"]*)")?\)'

# Table Row
TABLE_ROW_PATTERN = r'^\|(.+)\|$'