Knowledge Base for Context-Sensitive Help

Check out this post to know how to generate a static HTML knowledge base for your website that consists of step-by-step guides.

Let’s consider we already put this knowledge base to our website, you can see it here:

Now we can turn this knowledge base into a context-sensitive help file using MajorMindHelp and “Generate MMH wrapper” feature of Helpinator.

MMH wrapper is generally a MajorMindHelp help file that has no content in it and instead references HTML pages that are stored on an external website.

Basically the process is similar to the same that allows to turn a WordPress site into a context-sensitive help system for desktop applications described in this post:

Let’s say the generated knowledge base is in “C:\Project\help\kb” folder. If so, this folder should contain “_meta.xml” file generated along with the knowledge base. If it is not you should check “Create _meta.xml file when possible” option in the project settings.

Now select Main Menu->Tools->Generate code->Generate MMH wrapper for output.

Generate MMH Wrapper for a Knowledge Base

Save to – this is the full name of the mmh help file we are going to generate.

Base URL – base url of the knowledge base published on your website.

Path to the folder with “_meta.xml” file – the path to the generated by Helpinator knowledge base.

Select languages you’d want to add to the MMH file in the “Languages” list.

Knowledge base has it’s own very specific navigation, so we will not show any additional UI elements.

Now click “OK” and wait for the “Done!” message. Now you have a “.mmh” file that you can pass as a parameter to the MajorMindHelpViewer and open articles with specified context ids.

You can download and run this compiled demo to test it:

Note that you also need to download and install MajorMindHelpViewer:

How to Create a Knowledge Base With Step-By-Step Guides

In this tutorial we will cover two interesting features of Helpinator at once. The first one is called “Step-by-step guides“. It allows to define a sequence of actions or slides, each with a screenshot (optionally annotated) and text comment. You can then embed guides into topics and Helpinator will render them into output format accordingly to it’s specifications. Some output formats (like DITA or LiteHelp for example) support this content type out of the box, others, like GitHub markdown, require “emulation”.

Static Knowledge Base that Helpinator generates supports step-by-step guides and renders them as a user-controllable slideshow. It allows you to create knowledge bases for your company that contain easily understandable and navigatable procedures.

0. Planning a Knowledge Base structure

Helpinator has a versatile feature called Knowledge Base Profiles that allow to precisely define KB structure over Table of Contents created for tree-oriented outputs like user manuals. This is called “manual” mode. For this tutorial we will stick to “automatic” mode that just uses top-level topics as categories and all subtopics become articles in that category. The purpose of this tutorial is to create a Knowledge Base only, so we can design Table Of Contents with that in mind. Actually we can cteate ToC right when we create the project with ToC prototyping.

1. Creating a step-by-step guide

Step-by-step guides in terms of Helpinator are based on images (say, screenshots). It’s the basis. There is a number of ways you can collect screenshots for your guide:

1.1. Capturing with Helpinator

Helpinator has a built-in screenshot capture tool that allows to append captured images directly to a selected step-by-step guide.

Just enter the name of the guide to be created and Helpinator will append screenshots to this step-by-step guide as you capture them.

Capture into a guide

1.2. Capturing with any other tool (like TechSmith Snagit)

In this case you can paste captured images from clipboard directly to the guide editor.

Paste screenshot into guide editor

1.3. Already captured images stored in a Helpinator image library

In this case you can just select images in the library using checkboxes and click “step-by-step” icon.

Create step-by-step guide from selected images

1.4. Already captured images stored outside of Helpinator project

Same as 1.3. but you need to add images to the library first.

Add new images to the library
Click “Add images”
Image files selected
Images are in the library

2. Write step texts and titles

Now you can select the newly created guide in the project tree view and edit step texts and titles.

Edit step text and titles

3. Insert a guide into a topic

To insert a newly created guide into the topic open the topic editor and select “Insert” tab, then click “Step-by-step” and select the guide from the list.

4. Produce a Knowledge Base

To produce a knowledge base click on “Knowledge Base” icon on the main toolbar or select Main Menu -> Tools -> Compile Knowledge Base.

The default KB settings

This dialog allows to redefine project TOC to be KB-alike with categories and topics, but in our case we can leave to the auto generator, because we were after two-level KB-alike TOC right from the start.

Click OK and Helpinator will generate a static HTML Knowledge base for you.

Check out this sample KB:

Recommended Reading

1. Helpinator

Productivity Tools For Technical Writers Part 1

Productivity Tools For Technical Writers Part 2

Productivity Tools For Technical Writers Part 3

Productivity Tools For Technical Writers Part 4

Refactoring Documentation

2. WordPress

WordPress for Online Documentation: How To Use Helpinator plugin and documentation themes

WordPress for Context-Sensitive Help

Troubleshooting WordPress

3. Knowledge Base

How to Create a Knowledge Base With Step-By-Step Guides

4. LiteHelp

Introducing LiteHelp

LiteHelp For Delphi


ASCIIDoc/ASCIIDoctor: The easiest way to use it on Windows

6. Leanpub

Leanpub Tutorial

Productivity Tools For Technical Writers Part 4

1. To-do list

Helpinator allows to add to-do tasks to topics. You can add a task inside a topic editor and review them later in the global project to-do list.

To-do in topic editor
Global to-do list

2. Check links

“Check links” tool allows to check all topics for broken links.

Check links

3. Global Spellcheck

Global spellcheck is a kind of Quality Assurance tool that checks spelling in all topics of the project and allows to fix errors with a couple of mouse clicks.

Global spellcheck

Productivity Tools For Technical Writers Part 3

1. Paste code snippet

Code snippets like figures are a dedicated content item in Helpinator. We made it that way to apply syntax highlight and also because in some of the outputs (Leanpub, DITA for example) code snippets must be marked correspondingly. You can paste code snippets right into the topic editor using a dedicated command and it will create a corresponding snippet in the library.

Pasted code snippet

2. Slice code snippet

Sometimes you need to create a set of snippets from the same source file and it may take quite a time to crete them one-by-one. “Slice…” command makes it faster – select text, enter snippet id and click “Create”, then select another portion of text and so on…

Slice code sample

WordPress for Context-Sensitive Help

Publishing your end user documentation online has a number of advantages:

  • it improves your SEO and attracts new visitors
  • it is easy to update

However when you develop a desktop app you have to either duplicate content in your context-sensitve help system or get rid of this system and just open your website when a user presses F1.

MajorMindHelp solves this problem. It allows to turn any HTML-based content published on your website into context-sensitive help, including content published to WordPress.

Before proceeding please read this tutorial on how to publish your end user documentation to WordPress:

Check to create “_meta.xml”

Check your project options and see whether the “Create “_meta.xml” file when possible” is checked. In this case when you publish your content to WordPress Helpinator creates a system file that stores topic page URLs and context IDs.

Now publish to WordPress and then browse to your project folder, “wordpress” folder containing “_meta.xml” should appear there. We will need this file to generate MajorMindHelp file that “wraps” your WordPress site. Then you will be able to MajorMindHelpViewer as a context-sensitive help system with topics from your WordPress site.

In Helpinator select Main Menu->Tools->Generate Code->Generate MMH Wrapper for Output.

Generate MMH Wrapper

Save to – this is the file name to store your MajorMindHelp help file to.

Base URL – is the base URL of the documentation site. In our case it is “”. But it could be anything like “”, “”, depends on where you store your documentation.

Path to the folder with “_meta.xml” file – is the path where your generated “_meta.xml” file resides. Our main project file is in “C:\Project\Help”, so Helpinator generated xml file in the folder “wordpress” next to it (“WordPress” in this case is the name of the ouput format).

When you choose the path to “_meta.xml” Helpinator shows the list of languages stored in it. You can select what languages to include into MajorMindHelp file.

Visible UI elements – you can hide some of UI elements of MajorMindHelp viewer if you do not need them. For example, you can hide “Contents” tab and use table of contents of your HTML pages. In case of Helpinator WordPress themes you can use both modes – hide “Contents” or chose to hide navigation of WordPress theme. In this demo we choose to use the Viewer’s table of contents and hide the wordpress theme navigation.

Append this text to the end of topic URLs: this field allows to specify custom text that will be added to each topic URL when requesting content from the website. In case of Helpinator WordPress themes there’s a parameter named “nonav” that allows to hide theme navigation. And this is what we want to do becuase we prefer viewer’s navigation in this demo. So we need to set nonav param to 1: “&nonav=1”.

Now click “Generate” and wait for the confirmation.

Next step is to download and install MajorMindHelpViewer from our “Downloads” page:

The installer will create a file extension association for “.mmh”. So you will be able to launch help files with double-click from Windows Explorer.

So browse to the “C:\Project\Help\MMHWrapper\” and double-click “wordpress.mmh”. The viewer will launch and open our WordPress site:

WordPress site in MajorMindHelpViewer

The viewer allows to communicate with it via Windows messaging system, so you can tell it to open the topic you need, locate a keyword, execute search or switch language. At this moment we provide out-of-the-box solution for Delphi that allows to integrate MajorMindHelpViewer into your desktop Windows app like any other help system supported by Delphi. There’s a demo on how to do it inside the integration code package:

The viewer itself is free for commercial use, you can redistribute it along with your application, as long as you use outputs generated by a licensed version of Helpinator.

If you need to integrate context-sensitive help system of MajorMindHelpViewer with another development tool, please drop a line to and we will add it.

We will add more content sources soon, so if you need to use Confluence or Zendesk for context-sensitive help, please contact us too.

Troubleshooting WordPress

In most cases error messages that you get when you publish Helpinator content to WordPress are informative and easy to fix. Except two cases: “Access denied” and “Moved permanently”.

1. Access denied

Nowdays there are many shared hosting providers that block WordPress XML-RPC access by default. This is why you get this error message. There are two possible solutions for this problem – contact your hosting provider and ask them to allow XML-RPC or just rename xmlrpc.php file that is in the root folder of your WordPress installation to, say, xmlrpc123.php.

Helpinator allows to specify “Endpoint” in the “Publish to WordPress” settings dialog. Essentially it is the name of the xmlrpc.php file. So, in our case you can set it to xmlrpc123.php.

Setting “Endpoint” to the renamed xmlrpc123.php file

2. Moved permanently

Typically this problem arises from WordPress caching plugins, especially WP Super Cache and W3 Total Cache. The only way to fix it is to temporarily disable caching plugins before you publish content and then enable them back.

WordPress for Online Documentation: How To Use Helpinator plugin and documentation themes

If you missed the post about setting up your own local testing environment for WordPress check it out before reading this one:

Upon completion of WordPress setup you get to the Dashboard. Go straight to the “Plugins” section, we need to install 2 plugins:

  1. Helpinator Quick Publish plugin – extends WordPress XML RPC API so it becomes possible to publish pages in “packages”, not one-be-one which is time-consuming.
  2. WP-Reset plugin. In case you f-ck up with content, it’s better to reset your WordPress to a state of brand new than to remove piece-by-piece content that is messy.

To install a plugin:

1. Go to “Plugins” section of the Dashboard

Plugins – Dashboard

2. Click “Add new” button at the top. Then start typing “Helpinator” into the “Search” field on the right

Helpinator plugin

3. Click “Install now” then “Activate”

Activate plugin

Repeat the steps for “WP Reset” plugin.

Now we need to install Helpinator documentation theme. You can omit installing Helpinator theme if you wish the published content to fit into your current theme – not a problem, Helpinator will do that. However it is more convinient to browse technical documentation in a specialized layout, and this is what Helpinator themes do.

Open Helpinator downloads page and scroll to “WordPress” section: We will use “Modern” theme for this tutrorial, so download it.

Extract theme files to WordPress themes folder, in our case it is “C:\xampp\htdocs\www\\wp-content\themes\“, complete theme folder.

Helpinator WordPress online documentation themes are made to be child themes of your main theme, but you can use them as standalone themes too. However, by default, there’s a setting that this theme is the child theme of “twentynineteen”, the default WordPress theme. If you use another theme, or you want to use Helpinator theme as a standalone, you have to make alterations to styles.css file.

	Theme Name: Helpinator Modern
	Theme URI:
	Description: WordPress theme for use with Helpinator
	Version: 1.1
	Author: Dmitri Popov
	Author URI:
	Tags: HTML5, CSS3
        Template: twentynineteen
	License: MIT
	License URI:

See the “Template:” parameter that points to “twentynineteen” theme. Remove theme name if you plan to use Helpinator theme as a standalone theme, or change “twentynineteen” to the name of template you want other parts of your WordPress site to use.

All Helpinator themes only add one page template named “HelpinatorDocTemplate” (helpinator.php) that you need to choose as a page template when publishing content from Helpinator.

Let’s select Helpinator theme as our WordPress site theme. Open WordPress Dashboard and select “Appearance->Themes” from the left sidebar menu.

WordPress themes

Click on “Helpinator Modern” then “Activate”.

Activate Helpinator Theme

There’s one last thing left to do before we preceed to publishing. We need to add an empty root page for our documentation. You can skip this step if your create a documentation-only website, in other cases we will need to filter only documentation pages to show in our documentation Table Of Contents, and the easiest way to do it is to make all documentation pages children of one root page. So open “Pages” section of WP admin dashboard:

“Pages” section, “Add New”

We don’t need any specific content, so just name the new page “Documentation”, then click “Publish”.

Empty “Documentation” page

Now the initial setup is complete and you can move on and try to publish something from Helpinator.

Run Helpinator, open your project file and click “WordPress” icon on the toolbar:

“Publish to WordPress” on the main toolbar.

Click “+” sign to add a new WordPress site profile. Let’s name it XAMPP since we are going to publish to our tests site.

Fill in the “Host” name, in our case it is “” from this post:

We do not use SSL on our test site so do not check it.

Leave “Endpoint” field blank too, it is for complicated cases mostly. For example, when you rename your xmlrpc.php file to avoid problems or when your WordPress installation is in a subfolder (say “blog”), so in this case “Endpoint” should be “/blog/xmlrpc.php”

Fill your WordPress username and password. Note that Helpinator does not store your passwords, you will need to enter it on each session.

Fill in WordPress site details and check connection
Connection OK

Now we need to get the list of page templates and select “HelpinatorDocTemplate”. Leave “Parent” page empty because we do not want our docs to be attached to existing page. Check “WP site runs on Helpinator WordPress theme”, it will allow all dynamic content like step-by-step guides to appear correctly. They will work with other themes too, but as a static content only. Check “WP site has enabled Helpinator Quick Publish Plugin” because we have it. This will speed up publishing.

Page template, parent page, etc.

Now click “Save profile” – this will save you time because you will be able to use again the settings provided.

Click “Publish”. Note that it may take some time to finish.

When Helpinator finishes it will ask you to save your project. This is needed to store page ID’s of the published topics so Helpinator will be capable to update pages when you hit Publish button again and not create new ones.

When done head over to WordPress admin dashboard again. We need to do some settings customizations for our project to appear correctly. Remember empty “Documentation” page that we created to be the root page of documentation? Now we will set it to be the starting page of documentation theme, so WordPress will show only documentation pages in the documentation section.

Select “Appearance”->”Customize”.


Then select “Helpinator settings”.

Helpinator theme settings

Select our “Documentation” page as the TOC root page, then click “Publish”.

Select “Documentation” as the root page

Now we can preview our documentation section. From the “Pages” section of WordPress admin dashboard, hover the mouse cursor over one of the pages and click “View”.

Preview the page

The page might look like this:

Publlished topic page

Now let’s take some time and create a test navigation for our site. By default “twentynineteen” template does not have navigation so the rest of your site is unaware about the existence of the “Documentation” section.

Select “Appearance”->”Menus”.


Enter “mainmenu” as the menu name and click “Create Menu”.

Create a new menu named “mainmenu”

We are creating the primary site menu so select corresponding checkbox.

The primary menu

Select “View all” tab, then select “Home” page and the first page of our documentation (note that it’s NOT the “Documentation” page). Then click “Add to Menu”.

Now click on our first documentation page to roll down the settings and change navigation label to “Online Documentation” – this way it will appear in the menu. Then click “Save Menu”.

Alter navigation label

Now open the front page of our site. It should look like this, note the link to documentation section is now in the menu at the top of the page.

Front page menu

See that the rest of the site uses twentynineteen theme while documentation section uses Helpinator theme.

That’s all for this tutorial! Thank you for reading!

Setting up XAMPP to test WordPress site on Windows

XAMPP is an incredibly convinient development stack for Windows consisting of apache, php, mysql, mariadb and perl. You can use it to test your WordPress site publshed from Helpinator before releasing it to public.

Head over to XAMPP site ( and download Windows installer.

XAMPP website

Run the installer and follow steps. When asked for a folder enter “C:\xampp” or another folder OUTSIDE of “Program Files”.

XAMPP installation folder

When the installer finishes you are allowed to run XAMPP Control Panel which provides an easy way to Start/Stop services and alter configurations.

XAMPP control panel

But before we start anything let’s add our testing domain to Apache (because we wll have to restart it anyway). To add a new domain you will need to perform a set of actions (create html files folder, alter apache config and Windows hosts file so you can access your site by domain name from your web browser). But we wrapped all that into a handy tool that you can use to add domain names with a single click. Download it using this link:

XAMPP Add site tool

Now we can launch services, Apache and MySQL in particular. Click “Start” button next to the service name.

XAMPP Services Running

Click “Admin” button next to “MySQL” service, it will open PHPMyAdmin in your webbrowser. We will add a new database for WordPress using it.


Now click “Databases” tab. Enter “wptest” below “Create database” and click “Create”.

phpMyAdmin create database

Now go to WordPress site and download fresh WP.

Download WordPress

There’s “wordpress” folder in this package, extract files from this folder into our new site root, located at C:\xampp\htdocs\www\

Now we need to create WordPress configuration to continue. Locate wp-config-sample.php and rename it to wp-config.php. Open this new file in any text editor and set the following lines

// ** MySQL settings - You can get this info from your web host ** //
/** The name of the database for WordPress */
define( 'DB_NAME', 'wptest' );

/** MySQL database username */
define( 'DB_USER', 'root' );

/** MySQL database password */
define( 'DB_PASSWORD', '' );

We set DB_NAME to wptest database that we created, DB_USER to root and DB_PASSWORD to empty string. Of course in production server settings like this are a suicide, but we only need it for local testing.

Now you can delete index.html file that was created automatically by XAMPPAddSite as a stub. Then open your web browser and navigate to your domain name ( in our case). WordPress installer appears.

WordPress installer

Now you can complete your WordPress installation.

ASCIIDoc/ASCIIDoctor: The easiest way to use it on Windows

Helpinator allows to generate ASCIIDoc source file (with .adoc extension) that you can use in your ASCIIDoctor documentation toolchain or just employ to create HTML using beautiful templates that this generator provides. In any way you need to install ASCIIDoctor on your Windows system and given it’s Ruby origins it may become quite a task for a novice.

Good news is that there’s a JS-port of ASCIIDoctor that you can install via npm (node package manager) and use from the command line. Here are the steps.

1. Download Node.Js dsitribution package from It’s better to choose installer over other variants, because it will execute all required tasks like adding node to the PATH variable automatically.

2. Run the installer and follow the instructions. It’s better to choose the path outside of Program Files folder.

Node.js installer
Set path for node.js

Finish the installer and reboot your machine just in case.

Now you have Node Package Manager on your system and you can use it to install ASCIIDoctorJS.

3. Open command prompt and change current path to C:\nodejs (the folder where node.js resides on your system).

Now let’s install ASCIIDoctor via command line using npm:

npm i asciidoctor --save
npm i -g asciidoctor.js asciidoctor-cli

This will create asciidoctorjs.cmd file in node.js folder that will be available from command line.

4. Now let’s produce some ASCIIDoc sources from our Helpinator project. Select Main Menu -> Tools -> Batch Compile and add “ASCIIDoc” output, then specify folder path to save output to.

Batch job to compile ASCIIDoc

Click on lightning bolt icon and Helpinator will create .adoc file and images folder in the path specified.

Now we can get back to command line, change current folder to C:\Project\Help\ASCIIDoc and run asciidoctorjs to create HTML5 file from “Helpinator.adoc” file generated by Helpinator:

asciidoctorjs Helpinator.adoc

You will see generated .html file next to your .adoc file when the command finishes execution. Open it and enjoy impressive design work done for ASCIIDoc.

If you are too lazy to follow the procedure above, there’s a compiled source file of Helpinator help system in ASCIIDoc format on the “Download” page under “Sample Documentation” section.