Before the recent release of MadCap Flare 2021 (reviewed by me in this article), the only way of importing Markdown content into Flare was to use a third-party plugin called Markdown Plugin. While you can still use this in Flare 2021, another option is to use the new Markdown Import feature that is included within the new release. As I hinted within my review, there are pros and cons to each of these methods, and the best option for you will depend on a range of factors including previous experience of importing other document types such as Word or FrameMaker, your level of expertise with the command line interface (which is helpful when working with the plugin), and personal preference.
In this article, I look at both options, and take the opportunity to provide step-by-step guidance on how to create and configure a Markdown Import file using the new Markdown Import Editor. I’m going to focus on the scenario of maintaining the source content in Markdown and using Flare, not as an editor, but only as a way of publishing to HTML or PDF format.
Using Markdown Plugin
The latest version of this plugin is Markdown Plugin II, and it is available from Improvementsoft for an annual subscription of $59. Their free Kaizen plugin also provides basic support for converting Markdown documents, but Markdown Plugin offers more power and flexibility, including the ability to create snippets from Markdown source documents. A fundamental principle of both plugins is that each Markdown document is converted to a single Flare topic file, and there is no way to split the content into separate topics automatically based on headings.
With Markdown Plugin II, there are two actions you must do to add content from a Markdown source into your Flare project:
- Import the source Markdown documents. As a short-cut, you can place all of these documents within a single folder, and then import the contents of the folder in a single operation.
- Create a table of contents containing the resulting new topics. The plugin includes a command for automatically creating a table of contents based on folder structure; you can use this to automate the process of creating the table of contents if you organise the source Markdown documents into a folder structure (within the main folder that you are importing) that is based on the required structure of your TOC.
If you subsequently amend or add to the content of the source Markdown documents, you can update the corresponding content within Flare by simply deleting the previously imported topics and table of contents, and then repeating steps 1 and 2 above. And because the Markdown Plugin can be accessed from the command line, it is possible to create a batch file containing all three of these actions, which means that the entire process can be completed in a single operation by running the batch file. The batch file could even be added as a Pre-Build Event Command, thus ensuring that any generated output is always up-to-date.
Using Flare 2021 Markdown Import
Once a Markdown Import file has been set up, Flare 2021's Markdown Import enables you to import (or re-import) Markdown content in a single step. This is because the Import process automatically creates (or updates) the table of contents containing the imported topics, based on the heading structure. You can even set an option within Flare's Markdown Import file to automatically re-import the source Markdown whenever you generate output, ensuring that the published content is always up-to-date.
For the remainder of this article, I’ll take you through the steps of setting up and running the import process. As my source Markdown content, I’ll be using a single Markdown document that starts with a Heading 1, and is divided into sections and sub-sections using Heading 2s and Heading 3s. I’m going to assume that I would like each of the sections (starting with a heading 2) to become a separate topic in Flare, and that the heading 3s should become subheadings within the topics.
Markdown Import: step-by-step
When I'm setting up the import of Markdown, Word, or any of the other document types that Flare imports, I always prefer to create the Import file myself instead of using the Import Wizard (which is available from the Import icon on the Project ribbon). So, I'll right-click on the Imports folder within the Project Organizer, and click Add Markdown Import File.
In the Add File dialogue, I enter a name for the Import file I like to choose a name that summarises the content of the Markdown, such as "v5 Release Notes" or "Command Reference".
When the Markdown Import Editor opens, the first job is to Add the Markdown file(s) that you want to import. In my example, there is only one, but it is possible to add multiple files, or even to add a folder (in which case all the Markdown files within that folder will be imported). You can optionally select a folder into which the new topics will be created, but I will leave this blank so that the topics are added to the root (Content) folder.
Moving to the Styles tab, this is where we can configure some powerful settings that will split the content into separate topics and map various Markdown features to the required styles in my Flare stylesheet. You can optionally choose to associate a specific stylesheet, but I have not found that necessary for successful Markdown import.
For the Heading 2 style, I'll select the Start new topic on option. And since each of these heading is now at the start of a new topic, I'll map it to h1 in Flare. This means that I'll now have to map Heading 3 to h2 in order to avoid skipping a heading level within the resulting topics. Here are the resulting settings:
On the Advanced Options tab, I'll leave the Create new stylesheet option selected, because I don’t want Flare to touch my existing Master Stylesheet. Selecting the Convert all simple lists to paragraph lists is consistent with Flare's default setting of creating paragraph lists in the XML Editor, so I'll do this.
I want any images referenced within the Markdown content to be imported into Flare, and since I (in common with most other Flare users) usually keep all images within the Resources folder, I’ll select this option. As a result, the imported images will be placed in Content/Resources/Images.
Finally, since I plan to maintain the content in Markdown format outside of Flare, I'll select the two options beneath the Reimport heading. As a result:
- the resulting topics are linked, and I will see a warning message if I attempt to change them within Flare
- the topics will be updated automatically from any changes to the source Markdown whenever I build output from my project.
After configuring all these settings and saving the resulting import file, I can then initiate the import by clicking the Import button (indicated with a red arrow below).
If the Markdown source changes, the file will be re-imported automatically when I build output. I can also force an update at any time by opening the Import file and clicking Reimport.
Markdown Plugin II and the new Markdown Import in Flare 2021 both provide a streamlined workflow for maintaining content in Markdown format and publishing through Flare. Markdown Plugin can be automated by using the command line interface and batch files, and can also be used as the source for snippets in Flare. Flare's own Markdown Import offers the flexibility of enabling you to create new topics at headings and to map styles.
An in-depth look at MadCap Flare 2021's New Markdown Import Feature by Tom Johnson (I'd Rather Be Writing)
Impact of Coronavirus disease (COVID-19)
Our thoughts are with our peers within the global technical communication community whose lives have been affected by the current pandemic.
We continue to provide training and consulting on Flare, Help+Manual, and a range of user assistance technologies via the Web. As a result of current Europe-wide travel restrictions and official guidance on social distancing, we are unable to offer face-to-face training or consulting until further notice.
During these difficult times and while UK and other European government restrictions remain in place, we are offering the following:
- A free question and answer service by email, available to all, on any of these topics:
- Cascading Style Sheets (CSS)
- All MadCap Software products (including Flare, Central, and Lingo)
- EC Software's Help+Manual
(this service is normally only available to past students of UA Europe training courses)
- Reduced hourly rates for Web-based consulting and training
Please contact us for further information on these services.