Importing Markdown Files

How to Import Markdown Documents

1. Select Project > Import > Markdown Documents.

2. In the wizard, choose either Import into a new project (and complete the fields below) or Import into this project. However, if you do not have a project currently open, the file(s) will automatically be imported into a new project.

   • Project name Type a name for the new Flare project that will be created after you perform the import.
   • Project folder Click to find and select a folder.

   • Output type Select the primary target for your project.

     A target is a file that generates output from your project. You want your output to look and behave in a certain way, but not all authors have the same audience or work for the same company with the same needs and the same computer networking setup. Therefore, Flare lets you choose the best type of output(s) for your needs. A target file is used for each instance of an output type. And you can have many targets in your project (e.g., eight targets using PDF, two targets using HTML5). See Determining the Output Type and Step 4: Developing Targets.

     This page of the wizard lets you select a primary target as you get your project off the ground. This means that—although you can use more than one target for your project—you might use one target most of the time. By selecting a primary target, you will be able to use shortcut buttons to build, view, and publish its output more quickly. Also, when you open topics in the XML Editor, they will be displayed by default with the styles and other specifications associated with the primary target. However, you can use the Layout and Medium drop-downs in the local toolbar of the XML Editor to view topics with other settings.

     Do not worry if you're not yet sure of the best output type for your project. No matter which output type you select now, you can always change the primary target later.

3. Click Add file to choose Markdown documents. You can also select other options as necessary.

   Option	Description
   	This removes the selected file(s) from the list.
   	This lets you choose a folder, so that all files in that folder are added for the import.
   	This moves the selected file or folder lower in the list (if you have more than one to import).
   	This moves the selected file or folder higher in the list (if you have more than one to import). The file at the top is used for the name of the Flare TOC that is created as a result of the import. Also, the order determines how the imported files are arranged in the TOC as topics.
   	This opens the file that is selected in the list.

4. (Optional) On the left, select Styles. You can use this page to associate the project with an external stylesheet, restore mapping default settings, map the Markdown styles to Flare styles, and choose which styles should be the start of new topics.(Optional) On the left, select Styles. You can use this page for various style settings.

   Associate a Stylesheet

   This is purely optional. You can choose an existing stylesheet (such as one in the Flare project you are importing files into) by clicking . After doing this, styles from that stylesheet become available in the mapping drop-down fields below, so that you can map Markdown tags to those from the stylesheet you chose.

   

   Style Mapping

   • Restore defaults If you make mapping selections in the fields below but then change your mind, you can click this button, which will return the default settings.

   • [Drop-Downs] You can expand these sections to see the styles found in the Markdown document(s).

     • Block These are styles that take up the entire space in a line (e.g., paragraphs, headings)

     • List These are styles that are used to create bulleted and numbered lists. See Creating Numbered and Bulleted Lists and Types of List Styles.

     • Definition List These are styles that are used to create definition lists, which are typically groups of terms and definitions. See Creating Definition Lists and Types of List Styles.

     • Inline These are character-level styles that are applied only to certain words within a block (e.g., hyperlinks, bold text).

     

     Selecting Styles

     In these drop-down sections, you can map a style from the Markdown document(s) to another style.

     Flare automatically populates the "Map to" column with the recommended style. For example, if Heading 1 is found in the Markdown document, the recommended style to map to is h1 in Flare. Therefore, you often don't need to choose a different style. However, sometimes you might want something different. If you want to map the style to something other than what is recommended, click the drop-down in a cell to select a style.

     Example — Code Blocks

     You have a code block in the Markdown document, Flare initially maps it to the MadCap:codeSnippet style.

     

     If you leave this setting, the content will be brought in to Flare like this:

     

     However, you might want to map code blocks to the "pre" style instead.

     

     In that case, the content will be imported like this:

     

     Specifying New Topics

     If you want to specify that new topics should start with certain styles, expand the Block section and click the check box next to that style. The h1 style is selected by default (most authors start new topics on heading styles), but you can choose any block styles that you like.

     

   Preview

   When you select a style row, a preview is shown at the bottom so you can see how it looks.

5. (Optional) On the left, select Advanced Options. You can use this page to set various options. Click the quick Help buttons next to sections for more information.

   Styles

   • Create new stylesheet This creates a new stylesheet based on the settings you choose.

     

     If you disable this option, the styles resulting from the import will be added to the project’s primary stylesheet.

     

     Note If you choose to create a stylesheet when importing Markdown documents into a new project, that stylesheet will be automatically selected in the project properties. If you then open the Markdown Import Editor, deselect the option to create a new stylesheet, and reimport the documents, that stylesheet will continue to exist in the project.

   Topics

   • Convert all simple lists to paragraph lists If you leave this option disabled, bulleted and numbered lists will be imported so that each item in the list just has an <li> tag. If you enable this option, <p> tags will be added within each <li> tag. However, you can add <p> tags later manually for list items where you want them. The benefit of having <p> tags within list items is that you can easily add paragraphs or other content within that item before the next bullet or number is shown. See Creating Numbered and Bulleted Lists.

     Note Markdown supports both simple and paragraph lists. Although you can import simple lists as paragraph lists using this option, the reverse is not true. If you have paragraph lists in Markdown, they will not be converted to simple lists if you deselect the option. Those will just be imported as paragraph lists regardless of the option setting.

   • Convert all definition lists to definition paragraph lists If you leave this option disabled, definition lists will be imported so that each item in the list just has a <dd> or <dt> tag. If you enable this option, <p> tags will be added within each <dd> or <dt> tag. However, you can add <p> tags later manually for definition or term items where you want them. Most authors tend to create definition lists without <p> tags, but you can add them if you want. See Creating Definition Lists.
   • Approximate filename length Enter the maximum number of characters to use for naming topic files. The default is 24.

   Resources

   • Resources If the Markdown files have links to other files, such as images, you can select this option to include those files in the import. However, the files need to be located on your computer in order to be imported.
     • To project resources folder Select this to automatically import any extra files to the Resources folder in your project.
     • To folder Select this if you want to import the extra files into a specific folder, such as a subfolder under Resources, or even in a different folder in the Content Explorer. Then use the field below to choose the folder.

   Tables

   • Leave table styles as is This imports tables in a plain format with no styling.

   • Apply a selected table stylesheet to all imported tables This lets you select an existing Flare table stylesheet and apply it to all imported tables. That way, the imported tables will automatically have the look and feel associated with that table stylesheet.

   Reimport

   • Link generated files to source files Enable this if you want to continue editing in Markdown and reimport as needed. Deselect it if you want to edit the imported files in Flare going forward, severing the connection to the source files.
   • Auto-reimport before generate output If you selected “Link generated files to source files,” you will likely make future content changes in the source files. When you make such changes, the source files need to be reimported into the project so that they can be included in the output. You have the option of reimporting the files manually. However, you can use this option instead and let Flare reimport the files automatically when you attempt to build output.
6. Click Finish, then Accept.