workflow with Markdown?

This forum is for all Flare issues not related to any of the other categories.

workflow with Markdown?

Postby mattf on Wed Feb 06, 2019 4:12 pm

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
Matt F
You learn something new every day if you're not careful.
User avatar
mattf
Sr. Propeller Head
 
Posts: 276
Joined: Thu Feb 09, 2006 5:35 pm
Location: Next to the window

Re: workflow with Markdown?

Postby LorenaB on Wed Jun 19, 2019 8:15 am

*bump* anyone get anywhere with this?
LorenaB
Propeller Head
 
Posts: 12
Joined: Mon Jan 21, 2019 6:27 am

Re: workflow with Markdown?

Postby mattf on Wed Jun 19, 2019 8:24 am

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
Matt F
You learn something new every day if you're not careful.
User avatar
mattf
Sr. Propeller Head
 
Posts: 276
Joined: Thu Feb 09, 2006 5:35 pm
Location: Next to the window

Re: workflow with Markdown?

Postby doc_guy on Wed Jun 19, 2019 8:29 am

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.
User avatar
doc_guy
Propellus Maximus
 
Posts: 1947
Joined: Tue Nov 28, 2006 11:18 am
Location: Crossroads of the West

Re: workflow with Markdown?

Postby mattf on Wed Jun 19, 2019 11:03 am

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
Matt F
You learn something new every day if you're not careful.
User avatar
mattf
Sr. Propeller Head
 
Posts: 276
Joined: Thu Feb 09, 2006 5:35 pm
Location: Next to the window

Re: workflow with Markdown?

Postby jjw on Wed Jun 19, 2019 3:20 pm

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)
jjw
Sr. Propeller Head
 
Posts: 133
Joined: Thu May 08, 2014 4:18 pm
Location: Melbourne

Re: workflow with Markdown?

Postby MunchMan on Thu Sep 12, 2019 2:53 pm

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!
MunchMan
Propeller Head
 
Posts: 25
Joined: Mon Oct 19, 2015 9:35 am
Location: Seattle, Washington


Return to Flare's General Discussion

Who is online

Users browsing this forum: No registered users and 3 guests