Complete Guide to Creating Documentation Homepage and Custom Introduction Pages in Doxygen

Introduction and Problem Context

In software development, using Doxygen to generate API documentation has become a standard practice. Developers typically add detailed comments to their code, and Doxygen can automatically extract these comments to generate documentation containing elements such as classes, functions, file lists, and more. However, a complete documentation system requires not only technical explanations at the code level but also general information unrelated to code, such as project overviews, usage guidelines, and frequently asked questions. These contents are often unsuitable for direct embedding in source code comments but are crucial references for users to understand and use the SDK.

In practical scenarios, many developers face a common challenge when creating documentation for SDKs: how to place general content like project introductions and architectural descriptions on the starting page of the documentation, making it the first information users see when accessing the documentation. This requires adding custom homepage content without interfering with the automatically generated code documentation structure.

Core Solution: mainpage Command and .dox Files

Doxygen provides the dedicated mainpage command to address this issue. This command allows developers to define a main page in the documentation, which will serve as the entry point for the entire documentation. To use this feature, the most recommended method is to create an independent .dox file (or files with .txt or .doc extensions). These files are recognized by Doxygen as "additional documentation files"; they do not appear in the file index but can contain any documentation content that needs to be displayed.

The specific steps to create a mainpage.dox file are as follows: First, create a new text file in the project root directory or a dedicated documentation directory, naming it mainpage.dox. Then, write the content in this file using C/C++ style comment blocks. For example:

/*! \mainpage SDK Comprehensive Introduction Documentation

This page provides a comprehensive introduction to MySDK, including:
- Product Overview
- Key Features
- Quick Start Guide
- System Requirements

For detailed API references, please check the class list in the left navigation bar.
*/

Next, ensure that this file is included in the input file list in the Doxygen configuration file (typically Doxyfile). This can be done by setting the INPUT parameter to add the mainpage.dox file. For example:

INPUT = ./src ./include ./docs/mainpage.dox

After configuration, run Doxygen to generate the documentation, and the content from mainpage.dox will automatically become the homepage of the documentation. The main advantage of this method is the separation of code comments and project documentation, making maintenance clearer. Developers can freely edit the .dox file without modifying any source code.

Supplementary Methods: Markdown Support and USE_MDFILE_AS_MAINPAGE Option

With updates to Doxygen versions, native support for Markdown format was introduced starting from version 1.8.0. This allows developers to use the more concise Markdown syntax to write documentation pages. To use Markdown files as part of the documentation, first create files with .md or .markdown extensions. For example, create an introduction.md file with the following content:

# MySDK Introduction

This is an SDK introduction page written in Markdown.

## Main Features
- Feature One
- Feature Two

For detailed explanations, please refer to the API documentation.

Then, make corresponding settings in the Doxygen configuration file:

INPUT += introduction.md
FILE_PATTERNS += *.md *.markdown

Starting from Doxygen version 1.8.8, the USE_MDFILE_AS_MAINPAGE configuration option was also introduced, providing a more direct way to use Markdown files as the homepage. Developers can directly set an existing README.md file as the documentation homepage, with a configuration example as follows:

INPUT += README.md
USE_MDFILE_AS_MAINPAGE = README.md

This method is particularly suitable for teams that already use Markdown to maintain project READMEs, enabling consistent documentation management.

Implementation Recommendations and Best Practices

When choosing a specific implementation plan, project requirements and team workflows need to be considered. For most traditional C/C++ projects, using the mainpage command with .dox files is the most stable and reliable choice. This method does not depend on specific Doxygen versions and maintains consistency with existing code comment styles.

For modern development projects, especially those teams already extensively using Markdown for documentation writing, leveraging Doxygen's Markdown support may be more efficient. It is important to note that using Markdown features requires ensuring the Doxygen version is 1.8.0 or higher, while the USE_MDFILE_AS_MAINPAGE option requires version 1.8.8 or higher.

In actual deployment, it is recommended to include the documentation configuration file in the version control system to ensure all developers use the same documentation generation settings. Additionally, regularly check Doxygen version compatibility, especially in team collaboration environments.

Conclusion

By reasonably utilizing Doxygen's mainpage command, .dox file support, and modern Markdown integration features, developers can create comprehensive documentation that includes both detailed API references and complete project introductions. These methods not only solve the technical problem of integrating non-code content into the documentation homepage but also provide flexible choices to adapt to different project needs and team preferences. A well-structured documentation system can significantly enhance the usability and user experience of an SDK, making it an important aspect that cannot be overlooked in the software development process.