How to include custom files in Doxygen

I having been searching quite a lot before I found the answer, so I thought it would be nice to share!

According to this Doxygen gotchas article I finally found that: you need to add a file with the dox extension. Its content should contain C-style comment blocks:

/*!
  \page My test page
  contents
  ...
  more contents
*/

Make sure your custom files are placed in a directory which is included in INPUT setting or in the current directory if INPUT is left empty, so these files can be found.

Just for completeness: there are 3 possible extensions which doxygen treats as additional documentation files: .dox, .txt, and .doc.

Files which such extension are hidden from the file index. Inside the file you need to put one or more C/C++ style comment blocks.

For even more completeness, starting with Doxygen version 1.8 (I believe), it now supports additional text files which are very similar to markdown syntax. You no longer need to use C/C++ style comment blocks. Instead, just write almost normal text and make sure that the text file is in the INPUT path, and that your doxygen scan actually looks for files with .markdown extension (or any other extension you choose to use, like .md).

For clarity:

In the .dox configuration file, add the file to the INPUT directive with something like this:

INPUT = ../src \
        ../include \
        ../docs/my-extra-file.txt

If the file had the appropriate extension, say like .h or .c then Doxygen would find the file without adding to the INPUT directive. Inside the file use normal Doxygen tags, as in the source, i.e. inside comment blocks, like:

/*! \mainpage MyProject - A Brief Description.
\image html Mylogo.png
\section my-intro MyProject Introduction
\htmlinclude about-MyProject.html
*/

One can also just use one of the include tags, like the "\htmlinclude" in the above example, any where in the code.

Just list your custom files in the INPUT macro in your doxyfile. You can choose whatever name you find appropriate. Format is text with Doxygen tags.