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.

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++.

• 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.

The asciidoctor-mdpp gem is available on RubyGems.org.

To install it, add this line to your application's Gemfile:

gem 'asciidoctor-mdpp'

And then execute:

bundle install

Alternatively, you can install it directly from your terminal:

gem install asciidoctor-mdpp

You can convert a single AsciiDoc file to Markdown++ using the provided script:

./scripts/convert-mdpp-file.sh input.adoc

Or using Asciidoctor directly:

asciidoctor -r lib/asciidoctor/converter/mdpp.rb -b mdpp -o output.md input.adoc

For batch conversion of all .adoc files in a directory:

./scripts/convert-mdpp.sh <SOURCE_DIR> <OUTPUT_DIR>

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

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.

Bug reports and pull requests are welcome on GitHub at 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.

The gem is available as open source under the terms of the MIT License.

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.

Asciidoctor-MDPP is developed by WebWorks - Quadralay Corporation as an open-source contribution to the technical documentation community.