"Convert Markdown To AsciiDoc" Content Discussion

[jaredmorgs]

http://asciidoctor.org/docs/user-manual/#convert-markdown-asciidoc is currently available to create content for.

Use this issue as a tracker for content suggestions, or feel free to provide PRs referencing this ticket to keep track of contributions.

This content is contained in https://github.com/asciidoctor/asciidoctor.org/blob/master/docs/user-manual.adoc

[jaredmorgs]

Would need to verify this, but I think if you can paste generated Markdown HTML into AsciidocFX, it will do a pretty good job at converting the content to Asciidoc markup. I know that app does a great job for HTML to AsciiDoc in general, so it may be a migration strategy for folks.

It would be good to get @rahmanusta to comment on whether this functionality could be ported into the asciidoctor toolchain natively.

[mojavelinux]

The best solution right now is the IntelliJ plugin.

You are correct that AsciidocFX can convert HTML to AsciiDoc.

I also have a native converter in the works that uses kramdown to convert to AsciiDoc. I need to remind myself to push that repository. That's the native solution I'd like to put in the toolchain.

[rahmanusta]

@jaredmorgs I've used HTML and Markdown parsers written in JS to convert x to AsciiDoc. If there are parsers in Ruby for Markdown and/or HTML, it is not hard writing port to convert them to AsciiDoc.

[mojavelinux]

Exactly.

[mojavelinux]

Here's some high level conversion mapping:

https://github.com/graphitefriction/oscon-2013-docs-workshop/blob/master/convert-markdown-to-asciidoc.adoc

[jaredmorgs]

I'm moving https://github.com/opendevise/kramdown-asciidoc out of #85 into here to uncross the streams. ;)

[mojavelinux]

Actually, perhaps we can take this in a slightly different direction. I think we should create a new page called "converting to AsciiDoc" (or similar) that covers tools that help you get into the Asciidoctor ecosystem. We can then have a section per use case (phrased as "from X to AsciiDoc") in which we cover one or more tools that apply to it. We can always split it out into multiple pages in the future, but we'll start with a single page.

The page would go directly in the docs folder.

[jaredmorgs]

I think we should capture the tooling first, even if it isn't in the best position.

Once the basic info is documented and out there helping users, we can look at creating another page or remixing the content.

My approach with these edit-content issues is to just get the info trapped in tickets out into a centralized place, in atomic chunks.

[mojavelinux]

Sounds like a good plan.

[rockyallen]

The biggy in my world is MSWord to AsciiDoc. Unfortunately I don't have a perfect solution, but I have tried lots of methods! The best so far is Word->HTML->pandoc, supplemented by Word->Excel->CSV for tables. It renames all the images, fails on tables with more than 1 paragraph in a cell, and outputs old style AsciiDoc, but works. I assume lots of others have the same need - is it worth adding the section and asking specifically for input? See also http://discuss.asciidoctor.org/My-experience-using-Asciidoctor-with-a-windows-documentation-toolchain-tt4443.html#a4486 and http://thepaulrayner.com/blog/2013/02/14/word-to-asciidoc/

[jaredmorgs]

Have you tried copying the doc and pasting it into AsciidocFx? That editor can do amazing things with text.

On Fri, 11 Mar 2016, 23:59 rockyallen notifications@github.com wrote:

The biggy in my world is MSWord to AsciiDoc. Unfortunately I don't have a solution, but I have tried lots of methods! (The best so far is Word->HTML->pandoc, supplemented by Word->Excel->CSV for tables). I assume lots of others have the same issue - is it worth adding the section and asking specifically for input?

— Reply to this email directly or view it on GitHub https://github.com/asciidoctor/asciidoctor.org/issues/462#issuecomment-195375526 .

Sent from Mobile.

[mojavelinux]

We should definitely open a dedicated issue to discuss a new section about conversation from Word. There are several routes we could mention.

[toschneck]

The following two ways worked for me: 1) IntelliJ AsciiDoc Plugin

2) Pandoc

pandoc -s -S sakuli-api.md -t asciidoc -o sakuli-api.adoc

[mojavelinux]

The IntelliJ AsciiDoc Plugin is "in the family", so :+1:

While I recognize pandoc as a powerful tool, I don't often recommend it and would prefer to downplay mentions of it on the asciidoctor.org site. The reason is, we have no control over the AsciiDoc it produces and that AsciiDoc is not up to our standards. I've had to deal with some pretty bad situations that pandoc created, so any recommendation should carry that warning.

[mojavelinux]

I'd really like to see kramdown-asciidoc progress because I think that's the right approach. Kramdown is arguably the best / most accurate Markdown parser and its model is complete. That allows us to produce exactly the AsciiDoc we want.

If you are going to leverage pandoc for it's versatility of input support, then I would advise first converting to DocBook, then using docbookrx to convert to AsciiDoc. Again, that puts us in the driver's seat.