Any plans for adding markdown support?
-
- Propeller Head
- Posts: 30
- Joined: Tue Jul 22, 2014 6:30 am
- Location: Austin TX
Any plans for adding markdown support?
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
Has anyone tinkered with using markdown files and Flare together? I would bet they make strange bedfellows.
Thanks for your input
-
- Propeller Head
- Posts: 30
- Joined: Tue Jul 22, 2014 6:30 am
- Location: Austin TX
Re: Any plans for adding markdown support?
Well, shoot. Guess not
Re: Any plans for adding markdown support?
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
If you'd like to see markdown import in Flare, put in a feature request: https://www.madcapsoftware.com/feedback ... quest.aspx
-
- Propeller Head
- Posts: 30
- Joined: Tue Jul 22, 2014 6:30 am
- Location: Austin TX
Re: Any plans for adding markdown support?
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!
Re: Any plans for adding markdown support?
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.
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.
-
- Senior Propellus Maximus
- Posts: 4293
- Joined: Thu Feb 02, 2006 9:29 am
- Location: The Electric City
Re: Any plans for adding markdown support?
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?
New Book: Creating user-friendly Online Help
Paperback http://www.amazon.com/dp/1449952038/ or https://www.createspace.com/3416509
eBook http://www.amazon.com/dp/B005XB9E3U
Paperback http://www.amazon.com/dp/1449952038/ or https://www.createspace.com/3416509
eBook http://www.amazon.com/dp/B005XB9E3U
Re: Any plans for adding markdown support?
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.
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.
-
- Sr. Propeller Head
- Posts: 308
- Joined: Tue Jun 18, 2013 3:00 am
- Location: Eastern Seaboard, Thailand
- Contact:
Re: Any plans for adding markdown support?
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).
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).
Tom
Flare 2022, Capture 7
Flare 2022, Capture 7
-
- Senior Propellus Maximus
- Posts: 4293
- Joined: Thu Feb 02, 2006 9:29 am
- Location: The Electric City
Re: Any plans for adding markdown support?
And thanks for giving me some answers.wbrisett wrote:So, I think you're asking the right questions.
New Book: Creating user-friendly Online Help
Paperback http://www.amazon.com/dp/1449952038/ or https://www.createspace.com/3416509
eBook http://www.amazon.com/dp/B005XB9E3U
Paperback http://www.amazon.com/dp/1449952038/ or https://www.createspace.com/3416509
eBook http://www.amazon.com/dp/B005XB9E3U
Re: Any plans for adding markdown support?
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.
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.