How to import documentation from another help authoring tool
We have documentation that was generated using another help authoring tool. While HelpSmith seems like a better fit for our needs, we need to migrate the existing documentation in order to retain styles and other formatting.
Q: What is the best way to import the existing documentation into HelpSmith?
Using the HelpSmith's Import feature
In Helpsmith, you can use the File|Import feature that allows you to import documentation from various formats including:
Therefore, if your current help authoring tool allows you to create help files and documents in one of these formats, you can use HelpSmith's Import feature to import content from them.
Importing content with styles and formatting
In many cases, when you import content created using other documentation tools or editors, it may need manual editing to adjust formatting, styles, templates, etc.
For example:
HelpSmith uses templates which are mixed with the topic's content during the process of compiling a help system. But if you import an existing .CHM file or a Web Help system, the compiled help system does not have any data about templates. Therefore, you should separate the content from the HTML page's layout somehow.
Also, various text editors and documentation tools can use different approaches to formatting and styles, or use formatting elements supported by the original editor only.
Options to simplify the process of importing content
Therefore, in Helpsmith, we've implemented useful options to simplify the process of importing content from existing help files and documents in different formats, as explained below.
Extract content from HTML files
If you import content from a set of HTML files, or from a compiled .CHM help file, the Import feature allows you to extract content from selective HTML elements.
For example, if your HTML files contain content inside a <div class="my-content">...</div> element like this:
You can use a CSS selector to extract content from it:
This option allows you to exclude any unwanted parts. For example, it can be used to remove the header area from the imported topics since in HelpSmith, it will be generated by a template which contains the #TopicTitle variable, breadcrumb, and similar elements.
Similarly, you can use another selector to specify which elements should be ignored from the imported HTML files.
Importing styles from existing documentation
The Import feature allows you to import content with its original styles, or to replace the styles by the styles of the destination help project.
For example, you can import content and link it to the standard set of styles, such as Normal, Headings, Hyperlink, and others. This will make it easier for you to set up and adjust formatting by editing these styles through the Styles pane (View tab|Styles) instead of having to manually edit text formatting in each topic.
In addition, if you import files into an existing help project which already has topics, it is likely that you will want to use the styles from that help project rather than the initial styles from the imported documents.
Remark: The ability to replace styles is available for all supported formats including Word (.DOCX, .DOC), .RTF, .HTML, etc.
Using the Markdown format to import your content
If your previous help authoring tool can export documentation to the Markdown format, you can consider this format as an option to migrate your content to HelpSmith.
Since Markdown is a plain-text format with a limited number of formatting attributes (in comparison to HTML), it makes it easier to move content between different documentation tools.
BTW, when you import content, we recommend enabling the option to remove the title (Heading 1) from the imported topics. In HelpSmith, the title will be displayed by the #TopicTitle variable contained in a template, so there is no need to keep this title in the topic's body.
HelpSmith allows you to import the Table of Contents (TOC) hierarchy from:
Therefore, if your previous documentation tool can generate a .CHM help file, you can import your existing documentation from this format.
And since a .CHM file contains HTML files of topics in it, the option to selectively extract content is available when importing from the CHM format as well.