Custom Pages

doxygen can be also be used to create custom pages that are not part of the API of your library/program. The purpose of such pages is to enrich your documentation with anything else that you think the user may find useful.

To create custom pages, use one of the supported file extension: .dox, .txt, or .md. Doxygen will treat a .dox or .txt file as a C/C++ source file, and a .md file as a Markdown file.

For a .dox or .txt file, one can use a single doxygen comment, like so:

manual/index.dox

/** \mainpage My Library Manual
- Building
- Basics
- Examples
*/

You'll note that the \mainpage command was used, which tells doxygen to use this page as, well, the main page. For other pages, prefix them with the \page command.

By default doxygen will not know about these custom files, so we'll need to let it know through the INPUT attribute in our Doxyfile. For the about example add this line to your Doxyfile:

INPUT = manual/index.dox

Next, we may want to add the instructions on how to build the project, so we create manual/building/index.dox. As you read a bit more of the documentation, you will find out that doxygen supports a subset of the HTML tags, so we can write the following:

/** \page Building
 
<h2>Linux</h2>
<p>
  A simple way to build this project is with cmake, clone the repository, cd into the root of the project and run:
</p>
 
<pre>
  <code>
    mkdir my_build
    cmake -S . -B my_build
    cd my_build
    cmake --build .
  </code>
</pre>
 
*/

But you can of course also do the same using the popular Markdown notation:

# Building

## Linux

A simple way to build this project is with cmake, clone the repository,
cd into the root of the project and run:

    mkdir my_build
    cmake -S . -B my_build
    cd my_build
    cmake --build .

Scaling Up

Automatically Adding Files

At this point we could now go ahead and add manual/building/index.dox to our INPUT's with comma separation, but this might become annoying over time as we build up our manual, instead we'll just change it reference our manual folder:

INPUT = manual/

And set

RECURSIVE = YES

To make sure as we add any subdirectories of the manual as we create more organization and content.

Side Panel Treeview

As your manual scales up, you might want to also have a nice tree view to show you where you are in the manual to stay organized. This is easy enough to set up, turn it on with

GENERATE_TREEVIEW = YES

In your Doxyfile.

You'll recall that our manual/index.dox file is pretty bland, without any links pointing anywhere, by using the \ref command we can add links between various topics, and doing so will automatically start to populate our treeview.

If you notice that your tree is more like a pile of leaves then you can remedy this by checking out Subpaging.

This discussion should give you some direction on how to build a scalable manual to enrich your documentation, from here you might want to customize your layout.

Table of Contents

Custom Pages

Scaling Up

Automatically Adding Files

Side Panel Treeview