asciidoctor-mdpp 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d58ecb185224072cd87d0c5453f0091449464256085277d4c84f096dd9f50639
+  data.tar.gz: af21ce8f72001634f739cebff6f0b2ed449fb1b255d60fe33d773f1517a6d1fd
+SHA512:
+  metadata.gz: 7cf1aa43614a8a50fd1c93a5d31fbd4ff3a4209cba7b61c8ba476efb868f34be9dfd29f6b347dd4d4aad062170d437c7879976f4434707e423cd1ad0266b4e21
+  data.tar.gz: 4dcdba82e56d7e3bffdf59701011315784f5ca257301b382e6688ee954b7cc7b21de0f6bc5ac1729589a675b2087fb8bb6244dcd572a7fd454e311a7631c5fab

data/.memory-bank/activeContext.md

@@ -0,0 +1,84 @@
+# Active Context: Asciidoctor-MDPP
+
+## Current Work Focus
+
+The current development focus is on stabilizing and enhancing the Asciidoctor-MDPP converter with particular attention to:
+
+1. **Line Break Handling**: Improving line break recovery, especially in list items where the AsciiDoc AST drops continuation content after a trailing `+` character
+2. **Complex Table Rendering**: Refining the handling of multiline tables to better preserve source content fidelity
+3. **Test Coverage**: Expanding the test suite with additional edge cases to ensure robust conversion
+4. **Documentation**: Preparing documentation for the project's upcoming open-source release
+
+## Recent Changes
+
+Recent development efforts have addressed:
+
+- **Admonition Conversion**: Implemented proper handling of both fenced and short-form admonitions with correct style tags
+- **Image Handling**: Added support for dimensions and styling in image conversion
+- **Section Anchors**: Added support for explicit anchors in section headers
+- **Code Blocks**: Implemented support for code fences with language tags
+- **Page & Thematic Breaks**: Added handling for page breaks and thematic breaks (horizontal rules)
+- **Video Embeds**: Added support for YouTube video embeds
+
+## Development Patterns
+
+The project follows these active development patterns:
+
+1. **Test-First Development**: All new features begin with sample/expected fixture pairs before implementation
+2. **Strict Output Matching**: Tests validate conversion through byte-for-byte comparison of output with expected fixtures
+3. **Fallback Mechanisms**: Complex conversions implement fallbacks to ensure output is always generated, even with edge cases
+4. **Source Preservation**: Where AST information is insufficient, source file lookups are used to reconstruct the original content
+5. **Documentation Updates**: Development guidelines and specifications are updated alongside code changes
+
+## Key Insights & Learnings
+
+Working with the Asciidoctor AST has revealed several important insights:
+
+- **AST Limitations**: Some AsciiDoc features (like list item continuations) are not fully represented in the AST, requiring additional source processing
+- **Node Context Matters**: The same node type may require different handling based on its parent context (e.g., lists inside other lists)
+- **Source Processing Trade-offs**: Direct source parsing provides more control but introduces dependencies on source file availability
+- **Whitespace Sensitivity**: Exact reproduction of expected output requires careful handling of newlines, indentation, and whitespace
+
+## Decision Framework
+
+When implementing new conversion features, the following decision framework is used:
+
+1. **AST-first approach**: Attempt to use Asciidoctor's AST representation when it contains sufficient information
+2. **Source fallback**: When AST is insufficient, implement controlled source file lookups as a fallback
+3. **Graceful degradation**: When neither approach works, provide a clear but functional fallback (e.g., TODO comments)
+4. **Test validation**: Ensure all approaches are validated with comprehensive fixture-based tests
+
+## Next Steps
+
+The immediate development roadmap includes:
+
+1. **Line Break Recovery Enhancement**: Improve the source location fallback for list item breaks
+2. **Nested Content Support**: Enhance handling of deeply nested structures (lists within lists within blocks)
+3. **Error Reporting**: Add better error messages and warnings for problematic conversions
+4. **Performance Optimization**: Review and optimize source file lookups and processing
+5. **Documentation Completion**: Finalize documentation for open-source release
+6. **GitHub Preparation**: Completed preparation of the repository for public GitHub release by WebWorks - Quadralay Corporation.
+
+## Recent Changes
+
+- **Repository Preparation**: Updated `README.md`, created `CONTRIBUTING.md` and `CODE_OF_CONDUCT.md`, updated `LICENSE.txt` and `asciidoctor-mdpp.gemspec` for open-source release, including copyright and author attribution to WebWorks - Quadralay Corporation.
+- **Description Update**: Updated the gem's functional description in `gemspec`, `README.md`, `projectbrief.md`, and `productContext.md` to "Ruby-based Asciidoctor converter for converting AsciiDoc files to Markdown++ files."
+- **Cleanup**: Removed `codex.md` and the `.codex` directory.
+- **File Extension Clarification**: Clarified the use of the `.md` file extension for Markdown++ files and its backward compatibility benefits in `README.md`, `docs/mdpp-specification/overview.md`, and `productContext.md`.
+- **Company Name Standardization**: Standardized company name references to "WebWorks - Quadralay Corporation" across `LICENSE.txt`, `asciidoctor-mdpp.gemspec`, `projectbrief.md`, `progress.md`, `productContext.md`, `activeContext.md`, and `README.md`. Updated `gemspec` email to `development@webworks.com`.
+
+## Current Challenges
+
+The main technical challenges being addressed are:
+
+1. **Line Break Recovery**: The AST drops content after inline breaks in list items, requiring source reconstruction
+2. **Table Source Parsing**: Complex table structures benefit from direct source parsing, but this creates dependencies on source file availability
+3. **Strict Fixture Matching**: Tests require exact byte-for-byte matches, making whitespace and newline handling critical
+4. **AST Navigation**: Determining the context of nodes (e.g., whether a list is nested) requires careful parent/child relationship analysis
+
+## Collaboration Notes
+
+- **Commit Workflow**: Group related changes into focused, logical commits (fixtures, converter updates, documentation)
+- **Test Requirements**: All converter changes must be accompanied by fixture updates to maintain test coverage
+- **Code Style**: Follow Ruby conventions with frozen_string_literal and clean method boundaries
+- **Feature Documentation**: Document conversion details, assumptions, and limitations in the appropriate files under docs/

data/.memory-bank/productContext.md

@@ -0,0 +1,51 @@
+# Product Context: Asciidoctor-MDPP
+
+## The Problem
+Technical writers and documentation teams often face a challenging situation: they need to write content in a structured authoring format (like AsciiDoc) but need to deliver it in a format that's compatible with specific publishing systems or documentation platforms that use Markdown++.
+
+Without a reliable converter, authors would be forced to either:
+1. Manually translate AsciiDoc to Markdown++ (time-consuming and error-prone)
+2. Write directly in Markdown++ (losing AsciiDoc's powerful features)
+3. Use standard Markdown output (losing Markdown++'s enhanced capabilities)
+
+## What is Markdown++?
+Markdown++ is an enhanced variant of standard Markdown that extends the basic syntax with additional features. Importantly, Markdown++ files use the standard `.md` file extension to ensure backward compatibility with standard Markdown parsers.
+
+1. **Multiline tables** - Tables that can contain complex content spanning multiple lines, including lists, code blocks, and other Markdown elements
+2. **Style tags** - HTML comment-based syntax for applying custom styles to content (e.g., `<!-- style:AdmonitionNote -->`)
+3. **File includes** - Ability to include content from other Markdown++ files (e.g., `<!--include:file.md-->`)
+4. **Anchors and cross-references** - Enhanced linking capabilities through anchor comments (e.g., `<!-- #id -->`)
+
+These extensions make Markdown++ particularly well-suited for technical documentation while maintaining compatibility with basic Markdown parsers.
+
+## How Asciidoctor-MDPP Solves the Problem
+Asciidoctor-MDPP, a Ruby-based Asciidoctor converter for converting AsciiDoc files to Markdown++ files, bridges the gap between AsciiDoc's structured authoring capabilities and Markdown++'s publishing flexibility by:
+
+1. **Providing automated conversion** - Eliminating manual translation work
+2. **Preserving document structure** - Maintaining the hierarchy and relationships in the original AsciiDoc
+3. **Supporting Markdown++ extensions** - Translating AsciiDoc features to their Markdown++ equivalents
+4. **Enabling batch processing** - Converting entire documentation sets with a single command
+5. **Integrating with existing workflows** - Working with standard Asciidoctor toolchains
+
+## Target Users
+This converter is designed for:
+- Documentation teams using AsciiDoc for authoring but needing Markdown++ output
+- Technical writers who work across multiple documentation systems
+- Documentation toolchain engineers integrating multiple authoring and publishing platforms
+- Open-source projects wanting to maintain documentation in AsciiDoc while publishing to Markdown++-compatible platforms
+
+## User Experience Goals
+- **Seamless conversion** - Authors should be able to write in AsciiDoc without worrying about the conversion process
+- **High fidelity output** - The Markdown++ output should faithfully represent the original AsciiDoc content
+- **Easy integration** - The converter should work with existing Asciidoctor toolchains and workflows
+- **Clear error handling** - When conversion challenges arise, they should be clearly documented and reported
+- **Simple troubleshooting** - Users should be able to easily identify and address conversion issues
+- **Extensibility** - The system should accommodate future enhancements to both AsciiDoc and Markdown++
+
+## Business Context
+WebWorks - Quadralay Corporation is developing this project as an open-source contribution to the technical documentation community. By publishing it on GitHub, WebWorks - Quadralay Corporation aims to:
+- Support the broader documentation toolchain ecosystem
+- Enable more flexible documentation workflows
+- Demonstrate commitment to open-source development
+- Establish expertise in documentation conversion solutions
+- Potentially attract community contributions to enhance the converter's capabilities

data/.memory-bank/progress.md

@@ -0,0 +1,118 @@
+# Progress: Asciidoctor-MDPP
+
+## What Works
+
+The following features have been successfully implemented:
+
+### Core Document Structure
+- [x] Document-level layout and structure conversion
+- [x] Section headers with appropriate levels (`#`, `##`, etc.)
+- [x] Paragraphs with proper spacing
+- [x] Preamble handling
+
+### Block Elements
+- [x] Ordered and unordered lists with proper nesting
+- [x] Paragraphs with line breaks (using raw line processing)
+- [x] Tables (both simple and multiline)
+- [x] Admonitions (both fenced blocks and short-form)
+- [x] Images with dimension attributes
+- [x] Code blocks with language tags
+- [x] Literal blocks
+- [x] Example blocks
+- [x] Page breaks
+- [x] Thematic breaks (horizontal rules)
+- [x] Video embeds (YouTube)
+
+### Inline Elements
+- [x] Inline formatting (strong/emphasis)
+- [x] Inline images
+- [x] Anchors and cross-references
+- [x] Include directives
+
+### MDPP Extensions
+- [x] Style comments for admonitions, tables, etc.
+- [x] Multiline table support
+- [x] Include statement conversion (`include::file.adoc[]` → `<!--include:file.md-->`)
+
+## What's Left to Build
+
+### Conversion Enhancements
+- [ ] Improved list item line break handling
+- [ ] Better support for complex nested structures
+- [ ] Support for additional video providers beyond YouTube
+- [ ] Enhanced error reporting for conversion issues
+
+### Infrastructure
+- [ ] Comprehensive usage documentation
+- [ ] CLI improvements for batch processing
+- [ ] Configuration options for customizing conversion behavior
+- [x] Prepare for open-source GitHub release (including copyright and author attribution to WebWorks - Quadralay Corporation)
+
+## Current Status
+
+The project is in active development but already provides a solid foundation for AsciiDoc to Markdown++ conversion. It successfully converts most common AsciiDoc elements with good fidelity, with a few known limitations that are being addressed.
+
+### Readiness Assessment
+
+| Component | Status | Notes |
+|-----------|--------|-------|
+| Core Conversion | ✅ Ready | Basic document conversion working well |
+| Tables | ✅ Ready | Both simple and multiline tables supported |
+| Lists | ⚠️ Partial | Basic lists work, line breaks need improvement |
+| Admonitions | ✅ Ready | Both styles supported with correct styling |
+| Code Blocks | ✅ Ready | Code fences with language support working |
+| Images | ✅ Ready | Dimension attributes properly handled |
+| Includes | ✅ Ready | Properly converts to MDPP includes |
+| Videos | ⚠️ Partial | YouTube supported, other providers pending |
+| Documentation | 🟠 In Progress | Core docs exist, needs expansion |
+| Testing | ✅ Ready | Test framework in place with fixtures |
+| Error Handling | 🟠 In Progress | Basic handling exists, needs improvement |
+| Performance | ✅ Ready | Performs well for most documents |
+
+## Known Issues
+
+### List Item Line Breaks
+As documented in `docs/line-break-challenges.md`, there's a challenge with handling line breaks in list items:
+
+- **Root Cause**: Asciidoctor's AST drops content after a trailing `+` in list items
+- **Current Workaround**: Uses source location fallback to attempt recovery
+- **Limitations**: 
+  - Only works when source maps are enabled
+  - Requires access to the original source files
+  - May fail for complex nested content
+
+### Table Source Parsing
+Complex table handling requires direct source file access:
+
+- **Root Cause**: The AST does not preserve multiline cell structure
+- **Current Approach**: Parse the original source for tables
+- **Limitations**:
+  - Requires the original source files to be available
+  - Falls back to simple rendering for complex cases that fail parsing
+
+### Strict Fixture Matching
+Test requirements create some development challenges:
+
+- **Issue**: Tests require exact byte-for-byte matches, including newlines and whitespace
+- **Impact**: Small changes in whitespace can break tests
+- **Current Approach**: Careful handling of newlines and string trimming
+
+## Evolution of Project Decisions
+
+### Initial Approach
+The project began with a focus on AST-based conversion, assuming the Asciidoctor AST would contain all necessary information.
+
+### First Pivot: Source Access
+When AST limitations were discovered (especially for tables and line breaks), the approach evolved to incorporate source file lookups as a fallback mechanism.
+
+### Second Pivot: Testing Strategy
+The testing strategy evolved to use strict fixture matching, which uncovered subtle issues with whitespace and newline handling.
+
+### Current Direction
+The project now uses a hybrid approach:
+- AST-first for most conversions
+- Source lookups for complex structures
+- Carefully controlled whitespace and newline handling
+- Test-driven development with comprehensive fixtures
+
+This evolution has created a robust converter that balances fidelity with pragmatism, even in the face of AST limitations.

data/.memory-bank/projectbrief.md

@@ -0,0 +1,39 @@
+# Project Brief: Asciidoctor-MDPP
+
+## Overview
+Asciidoctor-MDPP is a Ruby-based Asciidoctor converter for converting AsciiDoc files to Markdown++ (MDPP) files. It provides a custom converter for transforming AsciiDoc documents into an enhanced variant of standard Markdown, extending the Asciidoctor framework with specialized conversion capabilities to handle unique Markdown++ features while preserving document structure and formatting.
+
+## Purpose
+The primary purpose of this project is to facilitate the conversion of technical documentation from AsciiDoc format to Markdown++ format, enabling users to leverage AsciiDoc's structured authoring capabilities while targeting systems that work with Markdown++.
+
+## Status
+The gem is currently in active development by WebWorks - Quadralay Corporation and is planned to be published as an open-source project on GitHub. The core conversion functionality is implemented and working well, though there are some known challenges with specific AsciiDoc features.
+
+## Goals
+- Provide a reliable and accurate conversion from AsciiDoc to Markdown++
+- Support all Markdown++ specific features including multiline tables, custom style tags, and file includes
+- Ensure high fidelity conversion that maintains document structure and formatting
+- Create a well-documented, maintainable, and extensible codebase
+- Establish a robust testing framework using Test-Driven Development (TDD)
+- Release as an open-source project to benefit the broader technical writing community
+
+## Key Requirements
+- Maintain a test-driven development approach for all feature additions
+- Support Markdown++ extensions like multiline tables, style tags, and includes
+- Handle AsciiDoc-specific features with appropriate Markdown++ equivalents
+- Provide comprehensive documentation for users and contributors
+- Ensure the converter is compatible with standard Asciidoctor workflows
+
+## Scope
+The project's scope encompasses:
+- Core converter functionality for AsciiDoc to Markdown++ transformation
+- Support for all standard AsciiDoc elements (headings, paragraphs, lists, tables, etc.)
+- Special handling for Markdown++ extensions and styling
+- CLI tools for batch conversion
+- Documentation for usage and contribution
+
+## Non-Goals
+- Support for converting Markdown++ back to AsciiDoc
+- WYSIWYG editing capabilities
+- Web-based conversion interface (focused on CLI/library usage)
+- Support for formats other than AsciiDoc and Markdown++

data/.memory-bank/systemPatterns.md

@@ -0,0 +1,122 @@
+# System Patterns: Asciidoctor-MDPP
+
+## Architecture Overview
+
+The Asciidoctor-MDPP converter is built on Asciidoctor's extension framework, specifically its converter system. The architecture follows these key patterns:
+
+```mermaid
+graph TD
+    AsciiDoc[AsciiDoc Source] --> Parser[Asciidoctor Parser]
+    Parser --> AST[Document AST]
+    AST --> MDPP[MDPP Converter]
+    MDPP --> Markdown[Markdown++ Output]
+    
+    subgraph "Converter Components"
+        MDPP --> NodeHandlers[Node-specific Handlers]
+        MDPP --> Extensions[Extension Processors]
+        MDPP --> Helpers[Helper Methods]
+    end
+```
+
+## Key Components
+
+### 1. Core Converter Class (MarkdownPPConverter)
+- Registered for the 'mdpp' backend with `.md` file output
+- Implements the primary `convert(node, transform)` method that dispatches to specific node converters
+- Follows the Visitor Pattern where different node types are handled by dedicated methods
+
+### 2. Node-Specific Handlers
+- Specialized methods for each node type (e.g., `convert_paragraph`, `convert_section`, `convert_table`)
+- Each handler is responsible for transforming a specific AsciiDoc node type to its Markdown++ equivalent
+- Follow naming convention of `convert_[node_type]` (e.g., `convert_list_item`, `convert_admonition`)
+
+### 3. Extensions
+- Include processor to transform AsciiDoc includes into Markdown++ includes
+- Extension system uses Asciidoctor's built-in extension mechanisms
+
+## Processing Flow
+
+1. Asciidoctor parses the AsciiDoc source into an Abstract Syntax Tree (AST)
+2. The MDPP converter traverses the AST, starting with the root document node
+3. For each node, the converter:
+   - Determines the node type
+   - Dispatches to the appropriate `convert_[node_type]` method
+   - Processes the node's attributes and content
+   - Recursively processes child nodes as needed
+   - Returns the converted Markdown++ content
+4. The final Markdown++ output is constructed by combining the results from all nodes
+
+## Design Patterns
+
+### Visitor Pattern
+The converter implements a visitor pattern by:
+- Defining a `convert` method that dispatches to specialized handlers
+- Using node-specific conversion methods to handle each node type
+- Traversing the document tree recursively
+
+### Default Fallback Pattern
+For unimplemented node types, the system:
+- Uses a TODO comment as a fallback (`<!-- TODO: [node_type] -->`)
+- Ensures graceful degradation for unsupported features
+- Provides clear indicators of unconverted content
+
+### AST Fallback Pattern
+For complex structures like tables:
+- First attempts to use source-based parsing for sophisticated rendering
+- Falls back to AST-based rendering when source parsing fails
+- Ensures consistent output even with malformed input
+
+### Recursive Conversion
+- Most container nodes recursively convert their children
+- Node parent-child relationships are maintained during conversion
+- Child blocks are joined with appropriate spacing based on context
+
+## Critical Implementation Paths
+
+### Table Conversion
+```mermaid
+flowchart TD
+    Table[Table Node] --> Check{More than\n2 columns?}
+    Check -->|Yes| SimpleAST[Simple AST-based\nTable Conversion]
+    Check -->|No| TrySource[Try Source-based\nMultiline Parsing]
+    TrySource --> Success{Successful?}
+    Success -->|Yes| MultilineTable[Emit Multiline\nMarkdown++ Table]
+    Success -->|No| FallbackAST[Fallback to\nAST-based Conversion]
+```
+
+### Admonition Conversion
+```mermaid
+flowchart TD
+    Admonition[Admonition Node] --> CheckType{Fenced or\nShort-form?}
+    CheckType -->|Fenced| ProcessBlocks[Process Child Blocks\nRecursively]
+    ProcessBlocks --> QuoteLines[Quote Each Line\nwith > Prefix]
+    CheckType -->|Short-form| QuoteRaw[Quote Raw Lines]
+    QuoteLines --> AddStyle[Add Style Comment]
+    QuoteRaw --> AddStyle
+    AddStyle --> Result[Final Markdown++\nAdmonition]
+```
+
+### List Conversion
+- Special handling for nested lists with proper indentation
+- Distinct conversion paths for ordered and unordered lists
+- Attempts to recover lost line breaks in list items through source location fallback
+
+## Error Handling and Recovery
+
+### Line Break Recovery
+- Paragraph line breaks (trailing `+`) are handled by processing raw lines
+- List-item breaks use a source location fallback mechanism
+- Graceful degradation when recovery isn't possible
+
+### AST Limitations Workarounds
+- Source file lookups for multiline tables
+- Custom parsing for retrieving information lost in the AST
+- Fallbacks for scenarios where AST information is insufficient
+
+## Testing Framework
+
+The testing framework follows a fixtures-based approach:
+- Sample AsciiDoc files in `spec/fixtures/samples/`
+- Corresponding expected Markdown++ output in `spec/fixtures/expected/`
+- Tests in `spec/converter_spec.rb` that validate conversion results
+- Strict byte-for-byte comparison for test validation

data/.memory-bank/techContext.md

@@ -0,0 +1,188 @@
+# Tech Context: Asciidoctor-MDPP
+
+## Technology Stack
+
+### Core Technologies
+- **Ruby**: Primary programming language (requires Ruby 3.0.0 or higher)
+- **Asciidoctor**: Base framework for document processing (version ~> 2.0)
+- **RSpec**: Testing framework for Ruby
+- **Bundler**: Dependency management
+- **Rake**: Task automation
+
+### Development Environment
+- **Git**: Version control
+- **RubyGems**: Package management and distribution
+- **Bash**: Shell scripts for conversion utilities
+
+## Development Setup
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/[USERNAME]/asciidoctor-mdpp.git
+cd asciidoctor-mdpp
+
+# Install dependencies
+bundle install
+
+# Setup development environment
+bin/setup
+```
+
+### Interactive Development
+
+```bash
+# Open an interactive console with the gem loaded
+bin/console
+
+# Install the gem locally for testing
+bundle exec rake install
+```
+
+## Build & Release Process
+
+```bash
+# Run tests
+bundle exec rspec
+
+# Build the gem
+gem build asciidoctor-mdpp.gemspec
+
+# Release a new version
+# 1. Update version in lib/asciidoctor/mdpp/version.rb
+# 2. Run:
+bundle exec rake release
+```
+
+## Project Structure
+
+```
+asciidoctor-mdpp/
+├── adoc/                   # Sample AsciiDoc documents
+│   └── samples/            # Various AsciiDoc examples
+├── bin/                    # Executables
+│   ├── console             # Interactive Ruby console
+│   └── setup               # Development environment setup
+├── docs/                   # Project documentation
+│   ├── conversion-guidelines.md
+│   ├── development-guide.md
+│   ├── line-break-challenges.md
+│   └── mdpp-specification/ # Markdown++ syntax specification
+├── lib/                    # Source code
+│   ├── asciidoctor-mdpp.rb # Main entry point
+│   ├── asciidoctor/        # Core module files
+│   │   ├── mdpp.rb         # Module definition
+│   │   ├── mdpp/           # Module components
+│   │   │   └── version.rb  # Version information
+│   │   └── converter/      # Converter implementation
+│   │       └── mdpp.rb     # Core converter logic
+├── scripts/                # Utility scripts
+│   ├── convert-mdpp.sh     # Batch conversion
+│   └── convert-mdpp-file.sh # Single file conversion
+├── spec/                   # Test specifications
+│   ├── converter_spec.rb   # Converter tests
+│   ├── spec_helper.rb      # Test setup
+│   └── fixtures/           # Test files
+│       ├── expected/       # Expected Markdown++ output
+│       └── samples/        # Sample AsciiDoc input
+├── .gitignore              # Git ignore patterns
+├── .rspec                  # RSpec configuration
+├── asciidoctor-mdpp.gemspec # Gem specification
+├── Gemfile                 # Dependencies
+├── LICENSE.txt             # MIT License
+├── Rakefile                # Rake tasks
+└── README.md               # Project overview
+```
+
+## Testing Framework
+
+### Test-Driven Development Workflow
+1. **Add sample**: Create a new AsciiDoc file in `spec/fixtures/samples/`
+2. **Define expected output**: Create corresponding Markdown++ in `spec/fixtures/expected/`
+3. **Update test spec**: Add test case to `spec/converter_spec.rb`
+4. **Run tests**: Execute `rspec` to verify conversion fails
+5. **Implement feature**: Add or modify converter code to handle the new case
+6. **Verify**: Run tests again to confirm successful conversion
+7. **Commit**: Save both the code changes and fixture updates together
+
+### Testing Commands
+
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run specific test file
+bundle exec rspec spec/converter_spec.rb
+
+# Run with detailed output
+bundle exec rspec --format documentation
+```
+
+## Technical Constraints & Limitations
+
+### Asciidoctor AST Limitations
+- List item inline breaks (trailing `+`) are problematic due to AST dropping continuation content
+- Source location info (`li.source_location`) is only populated when using `Asciidoctor.load_file` with `sourcemap: true`
+- Some table structures require direct source parsing rather than relying solely on the AST
+
+### Operational Requirements
+- For line-break recovery in list items, documents must be loaded with `sourcemap: true`
+- Table conversion requires access to source files for complex structures
+- Strict fixture matching requires precise handling of whitespace and newlines
+
+### Ruby Compatibility
+- Requires Ruby 3.0.0 or higher
+- Uses Ruby's standard library extensively (especially File I/O for source lookups)
+
+## Command Line Usage
+
+### Converting a Single File
+```bash
+# Using the script
+./scripts/convert-mdpp-file.sh input.adoc
+
+# Using Asciidoctor directly
+asciidoctor -r lib/asciidoctor/converter/mdpp.rb -b mdpp -o output.md input.adoc
+```
+
+### Batch Conversion
+```bash
+# Convert all files in a directory
+./scripts/convert-mdpp.sh <SOURCE_DIR> <OUTPUT_DIR>
+```
+
+### Programmatic Usage
+```ruby
+require 'asciidoctor/converter/mdpp'
+
+# Option 1: Direct conversion
+output = Asciidoctor.convert_file(
+  'input.adoc',
+  backend: 'mdpp',
+  safe: :safe,
+  require: 'asciidoctor/converter/mdpp',
+  attributes: { 'outfilesuffix' => '.md' },
+  header_footer: true,
+  to_file: false
+)
+
+# Option 2: Two-step conversion (for source locations)
+doc = Asciidoctor.load_file(
+  'input.adoc', 
+  safe: :safe, 
+  sourcemap: true,
+  require: 'asciidoctor/converter/mdpp', 
+  backend: 'mdpp', 
+  header_footer: true
+)
+output = doc.convert
+```
+
+## Ad-hoc Testing
+For rapid testing during development:
+
+```bash
+# One-liner to preview converter output
+ruby -Ilib -r asciidoctor/converter/mdpp -e "puts Asciidoctor.convert_file('spec/fixtures/samples/your.adoc', backend: 'mdpp', safe: :safe, require: 'asciidoctor/converter/mdpp', header_footer: true)"
+```

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-04-22
+
+- Initial release