Any plans for adding markdown support?

[kellyh_hochanadel]

Does anyone know if Flare has any plans to add support for importing markdown (.md) files as topics? I ask because most API doc automation tools (Swagger, Apiary, Blueprint, etc.) spit out one large markdown file. I see it as my life's mission to make these two worlds work together, since most of these tools are built with developers in mind, not content creators.

Has anyone tinkered with using markdown files and Flare together? I would bet they make strange bedfellows.

Thanks for your input

[kellyh_hochanadel]

Well, shoot. Guess not

[NorthEast]

I'd imagine most markdown editors would be able to produce a HTML file, and you can import HTML into Flare.

If you'd like to see markdown import in Flare, put in a feature request: https://www.madcapsoftware.com/feedback ... quest.aspx

[kellyh_hochanadel]

I could use a PowerShell tool like Pandoc to convert the markdown to HTML, but I not-so-secretly hoped I could avoid the middleman. I'll add it as a feature request!

[wbrisett]

I think the biggest challenge with markdown is there isn't a spec on it. In fact, there are some people interested in making a spec for it, but John Gruber who came up with markdown is being weird. He claims ownership of the term markdown, but doesn't want a spec for it and it more or less bullying folks who are trying to make a spec for it. So much so, that the group has taken to calling it CommonMark <http://commonmark.org>. If CommonMark takes off (I think it will personally), then Madcap has something to work with. But until there is some sort of standardization, there's not much hope in creating a standard import for flare in my opinion.

I would be curious to know if all flavors of markdown you're using are identical? Are you using more than just a single tool's output or multiple tools to produce output? I ask because I've always thought markdown would be a quick and convenient way to get developers to document things. However, there weren't any real solutions when it came to converting them into DITA or Flare. But, I might be willing to script something that would work. PM me and let's talk.

[RamonS]

I need some enlightenment here. What does markdown/CommonMark bring to the table that the wiki markup doesn't (it looks very similar to me)? Is this just another simplified markup syntax because we do not have enough conventions already? How does this benefit over having a plain HTML based file?

[wbrisett]

Ramon:

In reality both markdown and wiki markup are similar. Markdown is used on stack overflow, github, and other sites, wiki markup yet on others. Both have been around a while, and both have some flaws when doing things like tables. However, both are used all over the place. You're right about one thing, we don't have enough do we? There's also Creole and ReST, and I'm sure a bunch of other more obscure one's out there. But on the web both Markdown and Wiki markup are both quite popular. Outside of the web, I've seen Markdown more often. Both tend to have parsers that build everything as HTML, but from experience I don't think I would want to bring that directly into Flare (I've only had so-so luck doing that).

To answer your final question how is one a benefit over HTML? I'm really not sure there's much real benefit. Again, I think the challenge with Markdown is lack of a standard and both have issues with more complex table markups.

So, I think you're asking the right questions. However, if handed markdown as part of the output, as the original poster was, the question is how can I make it easier to import. She is simply looking for a one stop shop instead of having to run it through one parser, then import that. My thought is run it through a script with valid Flare XHTML as the output, then you don't have to run it through the parser. It's quick and painless, but I'd need to do some testing to see if there are any gotcha's.

[atomdocs]

I agree that direct import of markdown to Flare would be a useful feature - thanks for the commonmark link, wbrisett.

For the OP, it is a question of pulling source documentation directly into Flare. It could also provide an easier path for fast prototyping. I follow Nita Beck's excellent process (http://beck-communications.com/2013/12/ ... ject-pt-1/), but markdown could be a useful addition for jump-starting new projects (by avoiding Word).

[RamonS]

So, I think you're asking the right questions.

And thanks for giving me some answers.

[wabernat]

I realize it's been a few years since anyone asked, but this tool does the trick: https://www.kaizenplugin.com/

It does two things really well: it pulls a big markdown file into Flare, and if you tell it to, it breaks up the resulting file by heading level into separate topics. If you are getting Flare info directly from a markdown engine, this is a huge time-saver.