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

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

Usage

Command Line Interface (CLI)

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>

Programmatic Usage

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.

Contributing

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.

License

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

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.