File: README — Documentation for kramdown-asciidoc (2.1.0)

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

Prerequisites

To install and run Kramdown AsciiDoc, you need Ruby 2.3 or better installed and a few RubyGems (aka gems). The instructions for installing the gems is covered 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.

Installation

Kramdown AsciiDoc is published to RubyGems.org as a gem named kramdown-asciidoc.

You can install the latest version of the gem using the following command:

$ gem install kramdown-asciidoc

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

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

Usage

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

$ kramdoc sample.md

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.

Note	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 sample.md

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

$ kramdoc -o - sample.md

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-url-scheme sample.md

Another use for attributes is setting the shared images directory, which is covered 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

![Octocat](images/octocat.png)

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 sample.md

Setting this attribute will produce the following document:

= Document Title
:imagesdir: images

image::octocat.png[Octocat]

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 sample.md

Setting this option will produce the following document:

= Document Title

image::octocat.png[Octocat]

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 sample.md

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=_ sample.md

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 sample.md

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=_ sample.md

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

API

In additional to the command-line interface, Kramdown AsciiDoc also provides a porcelain API (see API docs). 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 in the Kramdoc module:

Kramdoc.convert(source, opts) - convert a Markdown string or IO object to AsciiDoc
Kramdoc.convert_file(file, opts) - convert a Markdown file object or path to AsciiDoc

Note	`Kramdoc` is a 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 'sample.md'

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 'sample.md', 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!
EOS

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.

For more information about the API, refer to the API documentation.

Development

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 https://github.com/asciidoctor/kramdown-asciidoc

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

Note	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
end

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.

Generate code coverage

To generate a code coverage report when running tests using simplecov, set the COVERAGE environment variable as follows when running the tests:

$ COVERAGE=true bundle exec rake

You’ll see a total coverage score as well as a link to the HTML report in the output. The HTML report helps you understand which lines and branches were missed, if any.

Despite being fast, the downside of using simplecov is that it misses branches. You can use deep-cover to generate a more thorough report. To do so, set the COVERAGE environment variable as follows when running the tests:

$ COVERAGE=deep bundle exec rake

You’ll see a total coverage score, a detailed coverage report, and a link to HTML report in the output. The HTML report helps you understand which lines and branches were missed, if any.

As an alternative to deep cover’s native HTML reporter, you can also use istanbul / nyc. First, you’ll need to have the nyc command available on your system:

$ npm install -g nyc

$ yarn global add nyc

Next, in addition to the COVERAGE environment variable, also set the DEEP_COVER_REPORTER environment variable as follows when running the tests:

$ COVERAGE=deep DEEP_COVER_REPORTER=istanbul bundle exec rake

You’ll see a total coverage score, a detailed coverage report, and a link to HTML report in the output. The HTML report helps you understand which lines and branches were missed, if any.

Usage

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

$ bundle exec kramdoc sample.md

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

Alternatives

markdown-to-asciidoc (Java library)
pandoc (Haskell-based CLI tool)

Authors

Kramdown AsciiDoc was written by Dan Allen.

Copyright

See the LICENSE file for details.