Search code examples
markdownasciidoc

Including markdown in asciidoc

I tried to import a markdown file into an asciidoc file. In first sight it looks good but then it recognized that the markdown is not properly rendered as it's not asciidoc. This is my example: Markdown to be included:

Markdown to be included:

## heading 2

* list item
* list item 2
  * not properly rendered sublist

| broken | table |
|--------|-------|
| 1      | 2     |

Including asciidoc

= heading

include::imported.md[]

The markdown itself looks good: markdown

But included into asciidoc some elements break and it looks like it was interpreted an ascidoc: asciidoc

in my example:

  • nested lists are not shown properly
  • tables are shown wrong

Basically the question is: is there a way to include markdown into asciidoc so that it is properly interpreted and formatted?

Solution

  • I do not think it is possible to include a Markdown document in Asciidoc, but I know what I would do if I faced that problem.

    One approach is to convert each Markdown to Asciidoc and use the resulting Asciidoc files in your main document. If you have a fixed set of Markdown documents, which are legacy needing a one-time conversion, and then you can forget the original, this would be the way I would choose.

    If the Markdown documents are generated by some tool in your document-handling workflow, and you regularly need this, then you need to modify the workflow, including a conversion step.

    What I would also consider is using the Jamal preprocessor with Asciidoc. I wrote this tool a few years back. Currently, it has been released 2.0.2 at https://github.com/verhas/jamal.

    The tool is a preprocessor to any text format (plus MS Word) processing macros. Currently, there is no macro to convert a Markdown to Asciidoc, but writing one in Java is not too complex. I could do that if this need is general and not a particular one. With that, you could edit your Asciidoc file in IntelliJ and see the macro-included Markdown converted to Asciidoc on the fly on the preview pane.

    The current IntelliJ Asciidoctor plugin version of Jamal handles Markdown files this way. When it sees that you edit a .md.jam file, which means it is Markdown with Jamal macros, it processes the macros and converts the Markdown to Asciidoc for the plugin to display the processed file. The saved .md contains the original Markdown. A macro converting Markdown to Asciidoc can use the same conversion library.

    Just to be sure: I am not trying to sell anything. If you convince me there is a general need for such functionality, I will include it as a library open-source in the open-source Jamal tool in a later release. Or I can help you write this if you choose to do it.