MadCap Software Forums

I have developers that want to update a .md (Markdown) file as their source doc. It's a config file that mostly THEY do the writing in, and it's mostly code samples. I just tidy it up. Flare will import the .md file through the Kaizen Plug-in, but it won't output a .md file back for them. To give the devs an updated Markdown doc, I tried importing the .md file, making content changes but not otherwise fiddling with formatting or anything, outputting a defaultish Word doc (which loses all the "pre" styled code samples), then opening the Word doc in Typora, a Markdown editor. This doesn't work, and even if had worked, it's a clumsy, inelegant workflow. My understanding is that the import function (for .md as for other file types) is meant to be used just one time for a given document -- to get it into Flare -- and not as a continuous update mechanism.

Does anyone have any thoughts on this? It is true that a) Flare can import Markdown, b) Flare can output Word, and c) Word can be opened in Markdown editors, but it's a game of telephone... it's not the same thing coming out the other end. Has anyone done anything like this where the outcome was more, eh....felicitous?

Thanks,
-mdf

*bump* anyone get anywhere with this?

Not a peep on the post to date. I sounded my barbaric yawp, but it has found no echo in the community. (I'm constantly amazed at how often I seem to be the only user treading my particular path through the Madcap Funhouse.)
I learned some basic Markdown and we are leaving that document outside of Flare for the moment. I'll bring it into Flare just before release and work it over for PDF and HTML output.
Still waiting for a better idea.
-Matt

Have you checked with Mattias to see if he has any plans to create an export to markdown feature? It could work on a topic level, or you could apply it to a whole folder and it would output markdown files for all files in the folder, in the same structure they were created in. That is a plugin I think people would pay for.

Paul, I have not. It's a good idea and it would be worth paying for if it worked well. I'll ask him. Thanks,
-Matt

Have you tried running the html output through Pandoc? If the result is acceptable at least you could automate that with a build script. I played with Pandoc a bit and I can't say that the results were wonderful - but there are lots of Pandoc settings you can tweak. It might work ok if your markup is fairly simple.

The trouble with a more general "export a topic to markdown" tool is not just the conversion of html to markdown, but that you'd have to resolve all the Madcap specific components first - so you'd have to specify a target so you can look up variable settings and condition settings and then process the topic yourself (convert xrefs, expand snippets, etc - and then there's the images to deal with). Essentially you'd have to write your own publishing functions. It's not impossible, but it's arguably not worth the effort compared to just maintaining some content outside of Flare. Especially when a new version of Flare might break whatever you had done.

J (who tried doing this and regrets the lost hours of her life)

Please submit a feature request for this, I will too. Just started working with a major software company and their help source content is in crusty old Markdown docs. Really? Millions in revenue per year and that's the best you can do? Needless to say...have started mentioning Flare in my editing comments!

It appears the author of the Kaizen plugin also has a more fully-featured Markdown plugin. I haven't used it, but it could be what you're looking for:

http://www.kaizenplugin.com/content/plu ... plugin.htm

I'm thinking about adopting the same workflow, but I don't see a need for creating a Markdown file form Flare. One of the advantages of MD is that it's pure text, so it can be reviewed with standard code tools, like Github, Bitbucket, etc. The MD file would be fixed and only when it's approved (and merged into master), then the conversion to Flare would take place.