Skip to main content

Markdown Plugin

The plugin is based on the CommonMark specification. For more information, see the CommonMark specification.

You can download the latest installer from https://github.com/msander1983/MarkdownPluginRelease/releases/latest.

To purchase a license, go to gum.co/markdown2.

Import to Flare​

  • Import a folder with Markdown files to Flare topics.
  • Import a folder with Markdown files to Flare snippets.

Export to Markdown​

  • Export a Flare topic or snippet to a Markdown file.
  • Export a folder of topics and snippets to Markdown files.

Convert to Markdown​

  • Convert the current topic to Markdown.
  • Convert a folder of topics and snippets to Markdown.
  • Convert all topics and snippets in your Flare project to Markdown.

Refresh from Markdown​

  • Overwrite the content of the current topic with the converted content from its corresponding Markdown file.
  • Refresh all topics and snippets in a folder from the corresponding Markdown files.
  • Refresh all topics and snippets in your Flare project from Markdown.

If a topic is called Topic.htm, the corresponding Markdown file would be Topic.md, and for a snippet called Snippet.flsnp, the corresponding Markdown files is Snippet.flsnp.md.

Misc​

  • Convert a Flare topics to a Flare TOC file

Markdown Editor​

Use the built-in Markdown editor to see what your Markdown is converted to with the plugin.

Settings​

The settings for converting Markdown to Flare topics are set in a file called MarkdownSettings.xml, which is placed either in your Flare project, or in your application data folder in Windows. If a Flare project has a settings file - that file takes precedence over the settings file in the application data folder.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<Settings>
<HeaderlessTables>true</HeaderlessTables>
<ComplexTables>false</ComplexTables>
<RemoveAttributesOnExport>false</RemoveAttributesOnExport>
<ConvertXrefs>false</ConvertXrefs>
<ConvertLocalLinksToXref>false</ConvertLocalLinksToXref>
<ExportYaml>false</ExportYaml>
<UseMadCapCodeSnippet>false</UseMadCapCodeSnippet>
<ConvertedCommentedTags>false</ConvertedCommentedTags>
<ExportUnsupportedTagsAsComments>false</ExportUnsupportedTagsAsComments>
<ConvertCommentsToAnnotations>false</ConvertCommentsToAnnotations>
<CopyImages>true</CopyImages>
</Settings>

Import settings​

  • Convert to MadCap Code Snippet
  • Convert local links (and #-links) to cross-references
  • Convert commented out html tags (<!--<div>-->) to HTML
  • Convert //comments to MadCap:annotations
  • Copy images upon import
  • Import tables without adding headers to tables that don't have them.
  • Export YAML meta data.
  • Convert [[Wiki links]] to xrefs (only relevant for folder import).
  • Add GitHub repo URL meta data to imported files. /blob/main/ only
  • Convert [block:image] and [block:code] elements to <img> and <code> respectively.
  • Convert #keyword to <MadCap:keyword term=""keyword""/>
  • Merge adjacent empty table cells in a row.
  • Import tables with <tbody> and <thead>
  • Convert #-links to lower case

Export settings​

  • Export HTML elements without attributes to keep the Markdown clean.
  • Convert MadCap:xref to regular links on export.
  • Export unsupported tags as <!--<MyTag>--> comments.

YAML meta data​

If a Markdown file contains YAML dat, the YAML tags are converted to meta-tags in Flare.

  • There are a few special cases that are processed differently:
    • conditions are converted to the conditions of the topic or snippet.
    • conditionTagExpression are converted to the snippet conditions of the topic or snippet.
    • fileTags are converted to file tags for the topic or snippet.

For example,

description: Lorem ipsum dolor
keywords: lorem, ipsum, dolor
category: lorem

is imported into Flare as

<meta name="description" content="Lorem ipsum dolor" />
<meta name="keywords" content="lorem, ipsum, dolor" />
<meta name="category" content="lorem" />

and this YAML code

---
conditions: Default.Mobile,Default.Tablet
conditionTagExpression: include[Default.Mobile], exclude[Default.Tablet]
fileTags: Author.Author1,Author.Author2
---

is imported as

<html xmlns:MadCap="http://www.madcapsoftware.com/Schemas/MadCap.xsd" MadCap:conditions="Default.Mobile,Default.Tablet" 
MadCap:conditionTagExpression="include[Default.Mobile], exclude[Default.Tablet]"
MadCap:fileTags="Author.Author1,Author.Author2">

MarkdownCommander.exe CLI​

With the MarkdownCommander CLI you can import and export files using the command line.

The MarkdownCommander.exe file is located in your C:\...\Flare.app folder.

To import Markdown files to topics:

C:\>MarkdownCommander -import "C:\...\from-folder"" ""C:\...\to-folder"
C:\>MarkdownCommander -import "C:\...\from-folder\myfile.md" "C:\...\to-folder"
C:\>MarkdownCommander -import "C:\...\from-folder\myfile.md" "C:\...\to-folder\myfile.htm"

To export topics to Markdown files:

C:\>MarkdownCommander -export "C:\...\from-folder"" ""C:\...\to-folder"
C:\>MarkdownCommander -export "C:\...\from-folder\mytopic.htm" "C:\...\to-folder"
C:\>MarkdownCommander -export "C:\...\from-folder\mytopic.htm" "C:\...\to-folder\mytopic.md"
FlagComment
/fForce overwrite
/iInclude sub-folders
/tGenerate output to console (single file only)
/sSuppress dialogs.
/settings:[file]Uses a specific settings file for the Markdown import, e.g. "/settings:C:\users\mattias\my files\mySettings.xml"

To generate a TOC from a folder structure:

C:\>MarkdownCommander -toc "C:\my folder" "C:\...\myToc.fltoc"

If a folder is called "/My Folder/" and has a corresponding Markdown file called "My Folder.md" - that file is used is the parent topic for the node of that folder. Otherwise the folder node will be empty.

Ignoring files​

  • To keep files from being imported, you can set up a .markdownimportignore file in the source folder.
  • To keep files from being exported, you can set up a .markdownexportignore file in the source folder.

The syntax is based on wildcards, where

  • * represents a range of wildcard characters, and
  • ? represents a single wildcard character

To ensure that the .ignore rules are processed relative to the folder of the .ignore file the line in the ignore file must contain \.

Examples​

RuleComment
*\Lorem.mdExcludes the files called Lorem.md in any subfolder to the folder with the rule file
\Lorem.mdExcludes the Lorem.md file from the folder with the rule file
*Lorem*Excludes any file with Lorem in its full path.