Doxygen is as everybody knows, the de-facto standard for generating API documentation from source code comments. But it is also pretty great for generating user documentation, as is apparent from the Doxygen documentation itself. And with the really good Markdown support in recent versions, it is no longer necessary to write the documentation in “fake” code. Just plain Markdown works great.

There are a few gotchas, though, as I discovered when trying to generate a QT Assistant help file for the application I’m currently working on.

First you have to enable Markdown support in the Doxygen file if you want to use plain Markdown files. Do this with MARKDOWN_SUPPORT = YES. You also want to use USE_MDFILE_AS_MAINPAGE = mainpage.md to set the page that becomes index.html in the documentation.

Next, be aware that the index (or toc, or whatever your output format calls it) is generated in the order the pages are included in the Doxygen file. This means that you have to add each page separately to the INPUT variable.

Finally, note that the first level 1 heading is used for the page title, and subsequent headings are used for sections (and subsections) within the page. You must also make sure that the heading levels nest correctly, otherwise the generated help will break. Make sure you label all headings, otherwise they will not show up in the toc and you can’t reference them with @ref.

You can use either Doxygen tags or Markdown markup mixed however you want with a few exceptions:

• Don’t use @page for the page heading. Doing that will generate an extra empty page named from the page label that also appears in the index.
• It is OK to use @section for page headings, but be aware that Doxygen tags are processed before Markdown is expanded, so if you mix this with normal Markdown headings, they will appear in the wrong order in the toc.
• And probably more that I haven’t discovered yet.

Also note that images are not automatically copied to the output folder, you have to do that yourself. Images are also not added to the help manifest (index.qhp in my case). I solve that by putting the line

sed -i '' 's|<files>|&<file>*.png</file>|' help/index.qhp

in my make file. That makes sure any extra PNG files in the help folder gets included in the help file.