Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/asciidoctor/kramdown-asciidoc

A kramdown extension for converting Markdown documents to AsciiDoc.
https://github.com/asciidoctor/kramdown-asciidoc

asciidoc asciidoctor converter markdown

Last synced: about 11 hours ago
JSON representation

A kramdown extension for converting Markdown documents to AsciiDoc.

Awesome Lists containing this project

README 

        
= {project-name} (Markdown to AsciiDoc)

Dan Allen 

v2.1.0, 2022-07-04

// Aliases:

:project-name: Kramdown AsciiDoc

:project-handle: kramdown-asciidoc

// Settings:

:idprefix:

:idseparator: -

ifndef::env-github[:icons: font]

ifdef::env-github,env-browser[]

:toc: preamble

:toclevels: 1

endif::[]

ifdef::env-github[]

:status:

:!toc-title:

:note-caption: :paperclip:

:tip-caption: :bulb:

endif::[]

// URIs:

:url-repo: https://github.com/asciidoctor/kramdown-asciidoc

:url-asciidoc: https://asciidoctor.org/docs/what-is-asciidoc/#what-is-asciidoc

:url-asciidoctor: https://asciidoctor.org

:url-kramdown: https://kramdown.gettalong.org

:url-rvm: https://rvm.io

:url-rvm-install: https://rvm.io/rvm/install

:url-api-docs: https://www.rubydoc.info/github/asciidoctor/kramdown-asciidoc

:url-gem: https://rubygems.org/gems/kramdown-asciidoc

:img-url-gem: https://img.shields.io/gem/v/kramdown-asciidoc.svg?label=gem



ifdef::status[]

image:{img-url-gem}[Gem Version,link={url-gem}]

image:{url-repo}/workflows/CI/badge.svg[Build Status (GitHub Actions),link={url-repo}/actions?query=workflow%3ACI+branch%3Amain]

endif::[]



{url-repo}[{project-name}] (gem: *{project-handle}*, command: `kramdoc`) is a {url-kramdown}[kramdown] extension for converting Markdown documents to {url-asciidoc}[AsciiDoc].

Notably, the converter generates modern AsciiDoc syntax suitable for use with {url-asciidoctor}[Asciidoctor].



== Prerequisites



To install and run {project-name}, 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 {url-rvm}[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



{project-name} is published to RubyGems.org as a gem named *{project-handle}*.



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



== Usage



To convert a Markdown file to AsciiDoc using {project-name}, 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 [.path]_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 [.path]_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:



[source,markdown]

----

# Document Title



![Octocat](images/octocat.png)

----



You can extract the [.path]_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:



[source,asciidoc]

----

= Document Title

:imagesdir: images



image::octocat.png[Octocat]

----



If you want the [.path]_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:



[source,asciidoc]

----

= 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, {project-name} also provides a porcelain API (see {url-api-docs}[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 {project-name} API, pass the name of the file to the `Kramdoc.convert_file` method as follows:



[source,ruby]

----

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:



[source,ruby]

----

require 'kramdown-asciidoc'



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

----



To convert a Markdown string to an AsciiDoc string using the {project-name} API, pass the string to the `Kramdoc.convert` method as follows:



[source,ruby]

----

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:



[source,ruby]

----

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

----



The input string is automatically converted to UTF-8.



For more information about the API, refer to the {url-api-docs}[API documentation].



== Development



To help develop {project-name}, 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 {url-repo}[GitHub repository URL] and pass it to the `git clone` command:



[subs=attributes+]

 $ git clone {url-repo}



Next, switch to the project directory:



[subs=attributes+]

 $ cd {project-handle}



=== Prepare RVM (optional)



We recommend using {url-rvm}[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 {url-rvm-install}[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 [.path]_.ruby-version_ file at the root of the project.



=== Install the dependencies



The dependencies needed to use {project-name} are defined in the [.path]_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 [.path]_Gemfile_.



=== Run the tests



The test suite is located in the [.path]_spec_ directory.

The tests are all based on RSpec.



Most specs are scenarios, located under the [.path]_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:



[source,ruby]

----

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



or



 $ 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



* https://github.com/bodiam/markdown-to-asciidoc[markdown-to-asciidoc] (Java library)

* http://pandoc.org[pandoc] (Haskell-based CLI tool)



== Authors



*{project-name}* was written by {email}[{author}].



== Copyright



Copyright (C) 2016-2021 OpenDevise Inc. and the individual contributors to {project-name}.

Free use of this software is granted under the terms of the MIT License.



See the link:LICENSE.adoc[LICENSE] file for details.