asciidoctor-mdpp 0.1.1

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,121 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+*   Demonstrating empathy and kindness toward other people
+*   Being respectful of differing opinions, viewpoints, and experiences
+*   Giving and gracefully accepting constructive feedback
+*   Accepting responsibility and apologizing to those affected by our mistakes,
+    and learning from the experience
+*   Focusing on what is best not just for us as individuals, but for the
+    overall community
+
+Examples of unacceptable behavior include:
+
+*   The use of sexualized language or imagery, and sexual attention or
+    advances of any kind
+*   Trolling, insulting or derogatory comments, and personal or political attacks
+*   Public or private harassment
+*   Publishing others' private information, such as a physical or email
+    address, without their explicit permission
+*   Other conduct which could reasonably be considered inappropriate in a
+    professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our acceptable
+standards of behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the involved people for a specified period of time, including
+unsolicited interaction with those enforcing the Code of Conduct. This includes
+avoiding interaction in community spaces as well as external channels like social
+media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the involved people during this period, including
+unsolicited interaction with those enforcing the Code of Conduct. Violating
+these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of official interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html

data/CONTRIBUTING.md

@@ -0,0 +1,80 @@
+# Contributing to Asciidoctor-MDPP
+
+We welcome contributions to the Asciidoctor-MDPP project! By participating, you agree to abide by our [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## How to Contribute
+
+1.  **Fork the Repository**: Start by forking the `asciidoctor-mdpp` repository on GitHub.
+2.  **Clone Your Fork**: Clone your forked repository to your local machine:
+    ```bash
+    git clone https://github.com/YOUR_USERNAME/asciidoctor-mdpp.git
+    cd asciidoctor-mdpp
+    ```
+3.  **Install Dependencies**: Set up your development environment:
+    ```bash
+    bin/setup
+    ```
+4.  **Create a New Branch**: Create a new branch for your feature or bug fix:
+    ```bash
+    git checkout -b feature/your-feature-name
+    ```
+5.  **Implement Your Changes**:
+    *   Follow the existing code style and conventions.
+    *   All new features or bug fixes must be accompanied by new or updated tests.
+    *   Ensure all tests pass before submitting your changes (`bundle exec rspec`).
+    *   If you are adding a new conversion feature, please follow the Test-Driven Development (TDD) workflow outlined in `docs/development-guide.md` and `spec/fixtures/`.
+6.  **Commit Your Changes**: Write clear, concise commit messages.
+7.  **Push to Your Fork**:
+    ```bash
+    git push origin feature/your-feature-name
+    ```
+8.  **Create a Pull Request**: Open a pull request from your fork to the `main` branch of the upstream repository. Provide a detailed description of your changes.
+
+## Test-Driven Development (TDD) Workflow
+
+Our project heavily relies on TDD. When adding new conversion features:
+
+1.  **Add Sample**: Create a new AsciiDoc sample file in `spec/fixtures/samples/`.
+2.  **Define Expected Output**: Create the corresponding expected Markdown++ output in `spec/fixtures/expected/`.
+3.  **Update Test Spec**: Add a new test case to `spec/converter_spec.rb` that uses your new sample and expected output.
+4.  **Run Tests**: Execute `bundle exec rspec` to confirm the new test fails (as the feature is not yet implemented).
+5.  **Implement Feature**: Write the necessary code in `lib/asciidoctor/converter/mdpp.rb` (or related files) to make the test pass.
+6.  **Verify**: Run tests again to confirm successful conversion and that all existing tests still pass.
+7.  **Commit**: Commit both the code changes and the fixture updates together.
+
+## Cline Workflow and Memory Bank
+
+This project utilizes a "Cline Workflow" which is supported by a `.memory-bank` directory. This directory contains documentation files that provide context, design decisions, and progress updates for the project.
+
+### Memory Bank Structure
+
+The `.memory-bank` directory contains the following core files:
+
+*   `projectbrief.md`: Defines core requirements and goals.
+*   `productContext.md`: Explains why the project exists, problems it solves, and user experience goals.
+*   `activeContext.md`: Details current work focus, recent changes, next steps, and active decisions.
+*   `systemPatterns.md`: Describes system architecture, key technical decisions, and design patterns.
+*   `techContext.md`: Outlines technologies used, development setup, and technical constraints.
+*   `progress.md`: Tracks what works, what's left to build, current status, and known issues.
+
+### How to Use the Memory Bank
+
+*   **Before Starting Work**: Always read through the `.memory-bank` files to understand the current state, context, and any ongoing discussions or decisions.
+*   **During Development**: Refer to `activeContext.md` for immediate next steps and `systemPatterns.md` for architectural guidance.
+*   **After Significant Changes**: Consider updating relevant `.memory-bank` files to reflect new patterns, design decisions, or progress. This helps maintain a shared understanding of the project's evolution.
+
+By maintaining the `.memory-bank`, we ensure that all contributors have access to a comprehensive and up-to-date understanding of the project, facilitating smoother collaboration and onboarding.
+
+## Code Style
+
+*   Follow standard Ruby coding conventions.
+*   Use `frozen_string_literal: true` at the top of Ruby files.
+*   Maintain clean method boundaries and clear variable names.
+
+## Reporting Bugs
+
+If you find a bug, please open an issue on our [GitHub Issues page](https://github.com/quadralay/asciidoctor-mdpp/issues). Provide as much detail as possible, including steps to reproduce the bug, expected behavior, and actual behavior.
+
+## Suggesting Enhancements
+
+We welcome suggestions for new features or improvements. Please open an issue on our [GitHub Issues page](https://github.com/quadralay/asciidoctor-mdpp/issues) to discuss your ideas.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Quadralay Corporation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,113 @@
+# Asciidoctor-MDPP
+
+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++.
+
+## Features
+
+*   **Automated Conversion**: Seamlessly convert AsciiDoc to Markdown++.
+*   **Markdown++ Extensions**: Supports multiline tables, style tags, and file includes.
+*   **High Fidelity Output**: Preserves document structure and formatting.
+*   **Batch Processing**: Convert entire documentation sets with CLI tools.
+*   **Asciidoctor Integration**: Works with standard Asciidoctor toolchains.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'asciidoctor-mdpp'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install asciidoctor-mdpp
+```
+
+## Usage
+
+### Command Line Interface (CLI)
+
+You can convert a single AsciiDoc file to Markdown++ using the provided script:
+
+```bash
+./scripts/convert-mdpp-file.sh input.adoc
+```
+
+Or using Asciidoctor directly:
+
+```bash
+asciidoctor -r lib/asciidoctor/converter/mdpp.rb -b mdpp -o output.md input.adoc
+```
+
+For batch conversion of all `.adoc` files in a directory:
+
+```bash
+./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, recommended for complex docs)
+doc = Asciidoctor.load_file(
+  'input.adoc',
+  safe: :safe,
+  sourcemap: true,
+  require: 'asciidoctor/converter/mdpp',
+  backend: 'mdpp',
+  header_footer: true
+)
+output = doc.convert
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `lib/asciidoctor/mdpp/version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at [https://github.com/quadralay/asciidoctor-mdpp](https://github.com/quadralay/asciidoctor-mdpp). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Markdown++ File Extension and Compatibility
+
+Markdown++ files generated by Asciidoctor-MDPP use the standard `.md` file extension, not a custom `.mdpp` extension. This design choice is intentional and offers significant benefits:
+
+*   **Backward Compatibility**: Markdown++ files are fully backward compatible with standard Markdown parsers. This means you can render a Markdown++ file using any Markdown viewer or processor, and it will display as a regular Markdown document.
+*   **Ease of Use**: By using the `.md` extension, Markdown++ files can be seamlessly integrated into existing workflows and platforms that expect standard Markdown files, without requiring special handling or configuration for file types.
+*   **Enhanced Features via Comments**: Markdown++'s extended features (like multiline tables, style tags, and file includes) are implemented using Markdown-compatible syntax, often leveraging HTML comments. This ensures that while the advanced features are present and functional for Markdown++-aware processors, they gracefully degrade or are ignored by standard Markdown parsers, maintaining readability.
+
+This approach allows you to leverage the power of Markdown++ for enhanced documentation while ensuring broad compatibility and ease of adoption.
+
+## About WebWorks - Quadralay Corporation
+
+Asciidoctor-MDPP is developed by WebWorks - Quadralay Corporation as an open-source contribution to the technical documentation community.

data/Rakefile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+task default: %i[]

data/adoc/samples/demo.adoc

@@ -0,0 +1,19 @@
+= Demo Document
+Tony McDow
+:doctype: article
+:toc:
+
+== First section
+
+AsciiDoc is *really* easy to try.
+
+* Bullet 1
+** Bullet 1.1
+*** Bullet 1.1.1
+*** Bullet 1.1.2
+** Bullet 1.2
+* Bullet 2
+
+[source,ruby]
+puts "Hello, WebWorks!"
+

data/adoc/samples/nested_ulist.adoc

@@ -0,0 +1,14 @@
+= Sample Document
+
+This document tests nested unordered lists.
+
+== Test Section
+
+Here’s a top‐level introduction before the list.
+
+* Level 1 item A
+** Level 2 item A.1
+*** Level 3 item A.1.a
+**** Level 4 item A.1.a.i
+** Level 2 item A.2
+* Level 1 item B

data/adoc/samples/unordered-lists.adoc

@@ -0,0 +1,34 @@
+= Sample Document
+Author Name
+:toc:
+
+This document tests nested unordered lists.
+
+== Test Section
+
+Here’s a top‐level introduction before the list.
+
+* Level 1 item A
+** Level 2 item A.1
+*** Level 3 item A.1.a
+**** Level 4 item A.1.a.i
+** Level 2 item A.2
+* Level 1 item B
+
+// An open block to attach a paragraph under Level 1 item C
+* Level 1 item C
++
+--
+** Level 2 item C.1
+*** Level 3 item C.1.a
+--
++ This paragraph is attached to “Level 1 item C” (not to the nested list).
+
+* Level 1 item D
+** Level 2 item D.1
++ A continuation paragraph for “Level 2 item D.1”
+** Level 2 item D.2
+
+// Another top‐level list after a blank line
+
+* Final Level 1 item

data/docs/conversion-guidelines.md

@@ -0,0 +1,84 @@
+<!-- docs/conversion-guidelines.md -->
+# AsciiDoc → Markdown++ Conversion: Design Guidelines
+
+This document captures key design decisions, assumptions, and limitations of the MDPP converter.
+
+## Table Conversion
+
+- The converter supports two main table styles:
+  1. **AST-based simple tables** (more than two columns): uses Asciidoctor’s AST to extract header and body rows, compute column widths, and render a padded Markdown++ table.
+  2. **Grid-based multiline tables** (exactly two columns with multiline cell content): parses the raw source between `|===` fences to preserve cell grouping, then emits a two-column Markdown++ table with `multiline` style.
+- A **final AST fallback** wraps the entire grid parse in a `begin…rescue` to catch inconsistent fencing, missing fences, or nil comparisons. On error, it reverts to the simple AST-based renderer to guarantee conversion succeeds.
+- Challenges:
+  - Inconsistent AsciiDoc fencing (missing closing `|===`) caused `nil` index errors.
+  - Column width calculations needed nil-safe defaults.
+  - Preserving empty lines between logical row groups to match expected fixtures.
+
+## Admonition Conversion
+
+- Two rendering modes:
+  1. **Fenced blocks** (`[NOTE]` / `====…====`): convert child blocks (e.g., paragraphs, lists) recursively, then prefix each line with `> ` and prepend `<!-- style:Admonition<Type> -->` without a trailing blank line.
+  2. **Short-form blocks** (`NOTE:` in a paragraph): capture the raw lines, quote them verbatim, and append a trailing blank line to separate from following content.
+- Challenges:
+  - Distinguishing fenced vs. inline admonitions was required to control newlines correctly.
+  - Tests use strict equality, so extra or missing blank lines broke fixtures.
+
+## Image Macro Conversion
+
+- Single converter (`convert_image`) handles both block and inline images.
+- Parsing rules:
+  - **Alt text**: only the first positional attribute is used; if none, the `alt` is empty (`![]`).
+  - **Dimensions**: `width` and `height` can be numeric or percentage (e.g., `60%`), either as positional params or named attributes (`width="60%"`).
+  - **Style name**: built as `w<value>` and/or `h<value>` with `%` mapped to `percent` (e.g., `w60percent`).
+  - **Style comment**: only emitted when at least one dimension is specified: `<!-- style:w250h350 -->`.
+  - **pdfwidth** and other non-size attributes are ignored.
+- Inline images are processed via `convert_paragraph`, which gsubs on the `image:…[...]` pattern and reuses the same style logic.
+- Challenges:
+  - Handling mixed named and positional parameters.
+  - Ensuring inline and block conversions stay in sync.
+  - Avoiding extraneous style comments when no size is provided.
+
+## Strict Fixture Matching
+
+- Because tests perform byte-for-byte comparisons, every blank line, trailing newline, and space counts.
+- All converter methods (`convert_document`, `convert_admonition`, etc.) must be careful about where they append `\n`.
+  - For example, `convert_document` should not append an extra newline at end, to avoid unexpected blank line.
+  - Short-form admonitions append one trailing newline, whereas fenced admonitions do not.
+
+---
+_These guidelines will evolve as new edge cases appear. Please document any future converter gotchas here._
+## Line Break Challenges
+
+- Asciidoctor normalizes trailing `+` line breaks differently in paragraphs vs. list items:
+  - Paragraph breaks (trailing `+`) appear in `par.lines` and are handled by `convert_paragraph` by joining lines after stripping the `+`.
+  - List-item breaks are absorbed by the parser (AST loses the second line), so `convert_list_item` sees only the first segment.
+- The only reliable way to recover list-item breaks is a minimal file-aware fallback in `convert_olist`:
+  1. Call `convert(li, 'list_item')`. If it yields an empty or whitespace-only body, then
+  2. Use `li.source_location` to get the file path and line number.
+  3. Read that raw source line, strip the trailing `+`, emit `warn "path:lineno: inline '+' break in list item is not supported; text following the '+' has been dropped"` to `STDERR`, and use the remaining text as the list item.
+- Do not attempt to preprocess or rewrite `reader.lines` for this, as it breaks nested blocks, tables, and other constructs.
+- For nested list indentation, always check whether `ulist.parent.node_name == 'list_item'` instead of trusting `ulist.level`, which can vary in non-list contexts.
+
+## Session Summary (2025-04-30)
+
+### New Features
+- Anchors: explicit section anchors (`[[id]]`) are rendered as `<!-- #id -->` comments only for user-defined ids (not auto-generated).
+- Code and literal blocks: listing (`----`) and literal (`....`) blocks are emitted as triple-backtick fences, with language tags for `[source,lang]` blocks.
+- Page breaks: AsciiDoc `<<<` directives produce blank lines to indicate page breaks.
+- Thematic breaks: `'''` directives are converted to `---` horizontal rules.
+- Video embeds: `video::id[youtube,width=...,height=...]` macros produce YouTube `<iframe>` embeds with specified dimensions.
+
+### Assumptions
+- Section ids starting with the `idprefix` (default `_`) are considered auto-generated and skipped for anchor comments.
+- Code fences are not applied inside `example` blocks to preserve nested blockquote formatting.
+- Only YouTube provider is supported for video embeds; other providers will fall back to a TODO comment.
+- The converter intentionally omits a trailing newline at the end of output to satisfy strict fixture matching.
+
+### Design Decisions
+- In `convert_section`, detect explicit anchors by checking that `sec.id` does not start with the document’s `idprefix`.
+- In `convert_listing`, handle `listing` and `source` styles with code fences, and bypass fencing when the parent node is an `example`.
+- Introduce `convert_page_break` and `convert_thematic_break` to handle `<<<` and `'''` blocks as blank lines and horizontal rules, respectively.
+- For video macros, implement `convert_video` to render a YouTube `<iframe>` based on `target`, `width`, and `height` attributes.
+- Trim trailing newlines in expected fixtures rather than modifying spec comparisons to allow both behaviors.
+
+_End of session summary._

data/docs/development-guide.md

@@ -0,0 +1,95 @@
+<!-- docs/development-guide.md -->
+# Developer Guide
+
+This document summarizes key workflows, conventions, and architectural notes for contributors and coding agent sessions.
+
+## Testing and Fixtures
+- All feature work is done TDD-style: start by adding or updating a sample in `spec/fixtures/samples` and its corresponding expected output in `spec/fixtures/expected`.
+- Update `spec/converter_spec.rb` to include tests for new fixture files.
+- Run `rspec` to verify all tests, then commit both code changes and fixture updates together.
+- When writing tests that rely on node source locations (e.g., for inline-break recovery in list items), load documents with `Asciidoctor.load_file(..., sourcemap: true)` and call `doc.convert` rather than using `Asciidoctor.convert_file`. This ensures `source_location` is populated on AST nodes.
+
+## Converter Architecture
+- The core converter is `lib/asciidoctor/converter/mdpp.rb`, implementing a `convert(node, transform)` dispatch to `convert_<node>` methods.
+- Common patterns:
+  - `convert_paragraph`, `convert_image`, `convert_admonition`, `convert_ulist`/`convert_olist`, etc.
+  - For new Asciidoctor node types (e.g., tables), implement a `convert_table(node)` method.
+
+## Markdown++ Extensions
+- Specifications for language extensions (multiline tables, custom style tags, etc.) live under `docs/mdpp-specification/`.
+- Please refer to those spec files when implementing or updating features.
+
+## Documentation Updates
+- When workflow or conventions change, update this file to reflect the new process.
+
+## Helpful Tips
+- Use interactive inspect scripts (e.g., throwaway `inspect_*.rb`) to explore Asciidoctor AST nodes, then delete those scripts before committing.
+- Keep commits small and focused: fix root causes, update only relevant files.
+ 
+- Programmatically, you can invoke the converter from Ruby:
+  ```ruby
+  require 'asciidoctor/converter/mdpp'
+  output = Asciidoctor.convert_file(
+    'input.adoc',
+    backend:     'mdpp',
+    safe:        :safe,
+    # To enable recovery of source_location on nodes (e.g., for list-item inline-break tests),
+    # prefer using Asciidoctor.load_file with sourcemap: true:
+    #   doc = Asciidoctor.load_file('input.adoc', safe: :safe, sourcemap: true,
+    #     require: 'asciidoctor/converter/mdpp', backend: 'mdpp', header_footer: true)
+    #   output = doc.convert
+    require:     'asciidoctor/converter/mdpp',
+    attributes:  { 'outfilesuffix' => '.md' },
+    header_footer: true,
+    to_file:       false
+  )
+  ```
+ 
+- From the shell:
+  ```bash
+  asciidoctor -r lib/asciidoctor/converter/mdpp.rb -b mdpp -o output.md input.adoc
+  ```
+- Byte-for-byte fixture matching: tests compare the full output (including trailing newlines). When changing newline behavior, trim or add newlines in expected fixtures (e.g., `truncate -s -1 spec/fixtures/expected/file.md`) instead of altering specs.
+- Rapid ad-hoc conversion checks: use a Ruby one-liner to preview converter output, for example:
+  ```bash
+  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)"
+  ```
+- Distinguish explicit vs. auto-generated anchors: Asciidoctor auto-prefixes IDs with the document’s `idprefix` (default `_`), so emit only user-defined anchors by checking `sec.id` against that prefix.
+- Handling new block types: for each new node (e.g., `page_break`, `thematic_break`, `video`), implement a `convert_<node>` in `mdpp.rb`, add sample and expected fixtures, and update the spec.
+- Logical, focused commits: group related changes into separate commits (fixtures, converter/spec updates, documentation) with clear, descriptive messages.
+
+## CLI Wrapper and Batch Conversion Script
+- A helper script lives at `scripts/convert-mdpp.sh` to run the MDPP converter recursively over a directory tree.
+  - Usage: `./scripts/convert-mdpp.sh <SRC_DIR> <OUT_DIR>`
+  - It finds all `.adoc`/`.asciidoc` files under `SRC_DIR`, creates matching paths in `OUT_DIR`, and invokes:
+    ```bash
+    asciidoctor -r lib/asciidoctor/converter/mdpp.rb -b mdpp -o "$DST" "$SRC"
+    ```
+
+## Single-File Conversion Script
+- A helper script at `scripts/convert-mdpp-file.sh` converts a single AsciiDoc file to Markdown++ side-by-side.
+  - Usage: `./scripts/convert-mdpp-file.sh <INPUT.adoc>`
+  - Verifies the file exists and has a `.adoc` or `.asciidoc` extension.
+  - Outputs a `.md` file alongside the source with the same basename.
+  - Ensures the output ends with a trailing newline for strict fixture matching.
+
+## Fixture Tuning and Exact Matching
+- All tests perform strict string comparisons of output vs. expected fixtures.
+- Blank lines, trailing newlines, and precise spacing matter for passing tests.
+- When adding or modifying fixtures, use the diff in `rspec` output to identify mismatches and adjust the expected file accordingly.
+- The converter updates are synchronized with fixture tweaks in each feature commit to ensure consistency.
+
+Happy Converting!
+
+## CLI Wrapper and Batch Conversion Script
+- A helper script resides at `scripts/convert-mdpp.sh` to invoke the MDPP converter over a directory tree.
+- Usage: `./scripts/convert-mdpp.sh <SRC_DIR> <OUT_DIR>`
+- It scans for `.adoc`/`.asciidoc` files under `SRC_DIR`, mirrors the directory structure in `OUT_DIR`, and runs:
+  ```bash
+  asciidoctor -r lib/asciidoctor/converter/mdpp.rb -b mdpp -o "$DST" "$SRC"
+  ```
+
+## Fixture Tuning and Exact Matching
+- Tests compare outputs strictly (including blank lines, trailing newlines, and spacing).
+- When creating or updating fixture files, inspect the `rspec` diff and adjust expected files to match the converter’s output exactly.
+- Fixture updates should accompany code changes in the same commit to keep tests green.

data/docs/line-break-challenges.md

@@ -0,0 +1,29 @@
+## Inline-Break Challenges and Partial Recovery
+
+AsciiDoc hard line breaks (a trailing `+` at end of line) are handled differently depending on context:
+
+### Paragraph-level inline breaks
+- Asciidoctor represents a trailing `+` as an inline break, but using `par.content` drops them.
+- The converter now processes `par.lines`, strips any trailing `+` on each line, and joins lines with literal newlines:
+  ```ruby
+  lines = par.lines.map { |l| l.chomp("\n").chomp('+') }
+  text  = lines.join("\n")
+  ```
+- This restores hard breaks in normal paragraphs, image-macro paragraphs, admonitions, and most block contexts.
+
+### List-item inline breaks
+- **AST limitation**: For `olist` items, Asciidoctor splits at the break marker and drops the continuation from the AST; only the first segment remains.
+- **Fallback approach** (implemented but brittle):
+  1. Enable `sourcemap: true` when loading via `Asciidoctor.load_file` so that `li.source_location` is populated.
+  2. In `convert_olist`, inspect `li.source_location` to locate the raw source file and line number.
+  3. Read the raw file lines, strip trailing `+`, and collect all subsequent lines until the next list-item marker or a blank line.
+  4. Reconstruct the multi-line item by preserving the original numbering marker and indenting continuations.
+- **Limitations**:
+  - `source_location` is not set when using `Asciidoctor.convert_file` (the common conversion path), so fallback rarely triggers.
+  - Relative paths in `loc.path` require lookup via the document’s `docfile` attribute.
+  - The logic is brittle and may fail for nested lists and complex items.
+  - The converter currently emits `<!-- TODO: inline_break -->` placeholders for list-item breaks.
+
+### Future work
+- Consider writing an Asciidoctor extension to merge broken list-item segments before conversion.
+- Improve `convert_olist` fallback or switch to a preprocessor-based approach for robust recovery.