Kramdown AsciiDoc (gem: kramdown-asciidoc) is a kramdown extension for converting Markdown documents to AsciiDoc. Notably, the converter generates modern AsciiDoc syntax suitable for use with Asciidoctor.


To install and run Kramdown AsciiDoc, you need Ruby 2.4 or better installed and a few RubyGems (aka gems). We’ll explain how to install the gems in the next section.

To check whether you have Ruby installed, and which version, run the following command:

$ ruby -v

If Ruby is not installed, you can install it using RVM (or, if you prefer, the package manager for your system). We generally recommend using RVM because it allows you to install gems without requiring elevated privileges or messing with system libraries.


Kramdown AsciiDoc is published to as a pre-release gem named kramdown-asciidoc.

You can install the pre-release version using the following command:

$ gem install kramdown-asciidoc --pre

Installing this gem makes the kramdoc command available on your $PATH.

To test a feature that’s not yet released, you can run the application from source.


To convert a Markdown file to AsciiDoc using Kramdown AsciiDoc, pass the name of the file to the kramdoc command as follows:

$ kramdoc

By default, the kramdoc command automatically creates the output file sample.adoc in the same folder as the input file. This path is calculated by removing the Markdown file extension, .md, and replacing it with the AsciiDoc file extension, .adoc.

The converter assumes the input uses the GitHub-flavor Markdown (GFM) syntax.

If you want to direct the output to a different file, pass the name of that file to the kramdoc command using the -o option as follows:

$ kramdoc -o result.adoc

To direct the output to the console (i.e., STDOUT) instead of a file, use the special value - as follows:

$ kramdoc -o -

To see all the options the kramdoc command accepts, pass the -h option to the kramdoc command as follows:

$ kramdoc -h

For example, you can inject attributes (key/value pairs) into the header of the AsciiDoc output document using the -a option.

$ kramdoc -a product-name="ACME Cloud" -a hide-uri-scheme

Another use for attributes is setting the shared images directory, which is coverd in the next section.

Configure shared images directory

If the images in the source document share a common directory prefix, such as images/, you can configure the converter to extract that prefix, optionally promoting it to the document header.

Let’s assume you want to convert the following Markdown source:

# Document Title


You can extract the images/ prefix from the image reference and promote this value to the header of the output document by setting the imagesdir attribute:

$ kramdoc -a imagesdir=images

Setting this attribute will produce the following document:

= Document Title
:imagesdir: images


If you want the images/ prefix to be removed altogether and not added to the document header (i.e., an implied prefix), set the --imagesdir option instead:

$ kramdoc --imagesdir=images

Setting this option will produce the following document:

= Document Title


In this scenario, you may need to pass the imagesdir attribute to the AsciiDoc processor when converting the output document so the image is resolved, depending on where the image is stored.

Auto-generate IDs

You can configure kramdoc to automatically generate explicit IDs for each section title (aka heading) that doesn’t already have an ID assigned to it (in the Markdown source). To do so, simply enable the --auto-ids flag:

$ kramdoc --auto-ids

By default, kramdoc does not add a prefix to the generated ID and uses - as the separator / replacement character. You can change these values using the --auto-id-prefix and --auto-id-separator options, respectively:

$ kramdoc --auto-ids --auto-id-prefix=_ --auto-id-separator=_

Since the AsciiDoc processor generates an ID for any section title that doesn’t have one by default, you may decide you want to drop any ID which matches its auto-generated value. You can enable this behavior by adding the --lazy-ids flag:

$ kramdoc --lazy-ids

The catch is that kramdown/kramdoc and AsciiDoc don’t use the same prefix and separator when generating IDs. So it’s necessary to sync them. The simplest way is to set the --auto-id-prefix and --auto-id-separator values to match those used by AsciiDoc.

$ kramdoc --lazy-ids --auto-id-prefix=_ --auto-id-separator=_

If these values do not match the defaults in AsciiDoc, the idprefix and/or idseparator attributes will be assigned explicitly in the generated document.


In additional to the command-line interface, Kramdown AsciiDoc also provides a porcelain API. We use the term “porcelain” because the API hides the details of registering the converter, preprocessing the Markdown document, parsing the document with kramdown, and calling the converter method to transform the parse tree to AsciiDoc.

The API consists of two static methods:

  • Kramdoc.convert(source, opts) - convert a Markdown string to AsciiDoc

  • Kramdoc.convert_file(file, opts) - convert a Markdown file to AsciiDoc

Kramdoc is shorthand for Kramdown::AsciiDoc to align with the name of the CLI.

Both API methods accept the source as the first argument and an options hash as the second.

To convert a Markdown file to AsciiDoc using the Kramdown AsciiDoc API, pass the name of the file to the Kramdoc.convert_file method as follows:

require 'kramdown-asciidoc'

Kramdoc.convert_file ''

Like the command-line, Kramdoc.convert_file converts the Markdown file to an adjacent AsciiDoc file calculated by removing the Markdown file extension, .md, and replacing it with the AsciiDoc file extension, .adoc.

If you want to direct the output to a different file, pass the name of that file to the Kramdoc.convert_file method using the :to option as follows:

require 'kramdown-asciidoc'

Kramdoc.convert_file '', to: 'result.adoc'

To convert a Markdown string to an AsciiDoc string using the Kramdown AsciiDoc API, pass the string to the Kramdoc.convert method as follows:

require 'kramdown-asciidoc'

markdown = <<~EOS
# Document Title

Hello, world!

asciidoc = Kramdoc.convert markdown

If you want to direct the output to a file, pass the name of that file to the Kramdoc.convert method using the :to option as follows:

Kramdoc.convert markdown, to: 'result.adoc'

The input string is automatically converted to UTF-8.


To help develop Kramdown AsciiDoc, or to simply test-drive the development version, you need to retrieve the source from GitHub. Follow the instructions below to learn how to clone the source and run the application from source (i.e., your clone).

Retrieve the source code

Simply copy the GitHub repository URL and pass it to the git clone command:

$ git clone

Next, switch to the project directory:

$ cd kramdown-asciidoc

Prepare RVM (optional)

We recommend using RVM when developing applications with Ruby. We like RVM because it keeps the dependencies required by the project isolated from the rest of your system. Follow the installation instructions on the RVM site to setup RVM and install Ruby.

Once you have RVM setup, switch to the RVM-managed version of Ruby recommended by the project using this command:

$ rvm use

The recommended version of Ruby is defined in the .ruby-version file at the root of the project.

Install the dependencies

The dependencies needed to use Kramdown AsciiDoc are defined in the Gemfile at the root of the project. You’ll use Bundler to install these dependencies.

To check if you have Bundler available, use the bundle command to query the version installed:

$ bundle --version

If Bundler is not installed, use the gem command to install it.

$ gem install bundler

Then, use the bundle command to install the project dependencies under the project directory:

$ bundle --path=.bundle/gems
You must invoke bundle from the project’s root directory so it can locate the Gemfile.

Run the Tests

The test suite is located in the spec directory. The tests are all based on RSpec.

Most specs are scenarios, located under the spec/scenarios directory. Each scenario consists of a Markdown file that ends in .md (the given), an AsciiDoc file that ends in .adoc (the then), and an optional options file that ends in .opts. The test converts the Markdown to AsciiDoc (the when) and validates the result against what’s expected. The specification name of each scenario is derived from the directory name.

You can run all of the tests using Rake:

$ bundle exec rake

For more fine-grained control, you can also run the tests directly using RSpec:

$ bundle exec rspec

To run all the scenarios, point RSpec at the spec file:

$ bundle exec rspec spec/scenario_spec.rb

Run Individual Tests

If you only want to run a single test, or a group of tests, you can do so by tagging the test cases, then filtering the test run using that tag.

Start by adding the wip tag to one or more specifications:

it 'should do something new', wip: true do
  expect(true).to be true

Next, run RSpec with the wip flag enabled:

$ bundle exec rspec -t wip

RSpec will only run the specifications that contain this flag.

You can also filter tests by keyword. Let’s assume we want to run all the tests that have wrap in the description. Run RSpec with the example filter:

$ bundle exec rspec -e wrap

RSpec will only run the specifications that have a description containing the text wrap.


When running the kramdoc command from source, you must prefix the command with bundle exec:

$ bundle exec kramdoc

To avoid having to do this, or make the kramdoc command available from anywhere, you need to build the development gem and install it.



Kramdown AsciiDoc was written by Dan Allen.

Copyright © 2016-2018 OpenDevise Inc. (on behalf of the Asciidoctor Project). Free use of this software is granted under the terms of the MIT License.

See the LICENSE file for details.