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.
2. Check links
“Check links” tool allows to check all topics for broken 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.
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.
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…
Publishing your end user documentation online has a number of advantages:
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: https://www.helpinator.com/blog/2019/09/07/wordpress-for-online-documentation-how-to-use-helpinator-plugin-and-documentation-themes/
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.
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 “http://www.mydomain.com”. But it could be anything like “http://documentation.mydomain.com”, “http://www.mydomain.com/doc”, 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: https://www.helpinator.com/download.html#majormindhelp
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:
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: https://www.helpinator.com/downloads/mmhdelphi.zip
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 firstname.lastname@example.org 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.
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.
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.
If you missed the post about setting up your own local testing environment for WordPress check it out before reading this one: https://www.helpinator.com/blog/2019/08/27/setting-up-xampp-to-test-wordpress-site-on-windows/
Upon completion of WordPress setup you get to the Dashboard. Go straight to the “Plugins” section, we need to install 2 plugins:
To install a plugin:
1. Go to “Plugins” section of the Dashboard
2. Click “Add new” button at the top. Then start typing “Helpinator” into the “Search” field on the right
3. Click “Install now” then “Activate”
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: https://www.helpinator.com/download.html 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\mydomain.com\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: http://www.helpinator.com Description: WordPress theme for use with Helpinator Version: 1.1 Author: Dmitri Popov Author URI: http://www.dmitripopov.com Tags: HTML5, CSS3 Template: twentynineteen License: MIT License URI: http://opensource.org/licenses/mit-license.php */
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.
Click on “Helpinator Modern” then “Activate”.
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:
We don’t need any specific content, so just name the new page “Documentation”, then click “Publish”.
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:
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 “mydoman.com” from this post: https://www.helpinator.com/blog/2019/08/27/setting-up-xampp-to-test-wordpress-site-on-windows/
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.
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.
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.
Then select “Helpinator settings”.
Select our “Documentation” page as the TOC root page, then click “Publish”.
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”.
The page might look like this:
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.
Enter “mainmenu” as the menu name and click “Create Menu”.
We are creating the primary site menu so select corresponding checkbox.
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”.
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.
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!
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 (https://www.apachefriends.org/index.html) and download Windows installer.
Run the installer and follow steps. When asked for a folder enter “C:\xampp” or another folder OUTSIDE of “Program Files”.
When the installer finishes you are allowed to run XAMPP Control Panel which provides an easy way to Start/Stop services and alter configurations.
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: https://www.helpinator.com/downloads/xamppaddsite.zip
Now we can launch services, Apache and MySQL in particular. Click “Start” button next to the service name.
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”.
Now go to WordPress site and download fresh WP.
There’s “wordpress” folder in this package, extract files from this folder into our new site root, located at C:\xampp\htdocs\www\mydomain.com
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 (mydomain.com in our case). WordPress installer appears.
Now you can complete your WordPress installation.
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 https://nodejs.org. 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.
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.
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:
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.
None of us are perfect. And from time to time we write imperfect documentation. The documentation that is not bad in any sense but is just not 100% perfect. A perfectionist will go into all-out complete rewriting rage and will write something that is for 1% more perfect than it was. But a real writer will do the refactoring. Helpinator has some tools to help you with that.
1. Mighty TOC rearranger.
Helpinator allows to rearrange topics using drap-and-drop, but that is time-consuming. You can rearrange TOC like a plain text document using “Advanced rarrange” command.
2. Merge topics.
“Merge topics” command allows to combine several topics into a new topic. The new topic will be appended to the end of TOC.
3. Refactoring->Extract topic / Extract subtopic
Topic editor has a pop-up menu that appears when you right-click in the editor area.
Both commands allow to create new topic from selection. The former appends new topic to the end of TOC, the latter create a new subtopic of the current topic.
“Add topic” dialog appears, it allows to specify properties of the new topic that will be created from the selection.
4. Refactoring->Move selection to topic / Copy selection to topic
These two commands are in the same menu as pevious two. The only difference is that they do not create a new topic but instead allow to move/copy selection to existing topic. When you select this command, “Select topic” dialog appears that allows to choose topic to move/copy content to.
1. Cloned images
Helpinator allows to add callouts to screenshots/figures. Sometimes the screenshot is not that big, but the callouts are large or are in numbers. Another but similar situation is when you need to eplain different tasks based on the same screenshot. In both cases you have to double the image but it is a nightmare in terms of maintenance. The problem is so big that exprienced technical writers even try to avoid pictures whenever possible.
Helpinator solves this problem with “cloned” image. You can create one “donor” image and then define any number of “clones” that will inherit the screenshot but will have their own callouts. When the time comes to update the screenshot you only need to update one “donor” image.
2. Active region
Active region is a feature that you can use with cloned images. In many cases there’s no need to show entire screenshot in a cloned image, instead you only need a part of it. That’s where “active region” comes in hand. You can define a rectangular area on your image that will be rendered in the output instead of the whole large picture.
Note that there’s a rectangular region on the last image selected. This is the active region of the cloned image, so we will see only “Tools and Reports” section of UI in the output.
3. Integrate with 3rd party screenshot capture – Paste screenshot from clipboard
There’s a huge number of high quality screenshot capture tools available on the market, and you can use any of them as a companion to Helpinator. Screenshots/Figures are a dedicated content item in Helpinator, but storing screensots captured in another tool to file and then importing them to Helpinator is a pain. Instead there’s a dedicated editor command for it – “Paste screenshot/figure from clipboard”. It is available in “Image library”, topic editor and step-by-step guide editor.