From 3e4d619b4c4118c1631036b48c21d7af5b789076 Mon Sep 17 00:00:00 2001 From: ReenigneArcher <42013603+ReenigneArcher@users.noreply.github.com> Date: Thu, 3 Sep 2026 11:34:58 -0400 Subject: [PATCH] docs: Document Doxygen main page heading requirement This change adds an overview section to the README and documents an important Doxygen behavior: when using USE_MDFILE_AS_MAINPAGE, the first Markdown heading in the main page must be an H1. Starting with a lower-level heading can place page sections under the wrong navigation node. --- README.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 57a3247..26462d7 100644 --- a/README.md +++ b/README.md @@ -9,10 +9,20 @@
- SonarCloud + SonarCloud
-## Usage +# Overview + +This repository provides the common Doxygen configuration used by LizardByte projects. It includes shared Doxygen +defaults, Doxygen Awesome styling, custom aliases, and CMake and Read the Docs integration. + +## 🚀 Usage + +> [!IMPORTANT] +> When using a Markdown file with `USE_MDFILE_AS_MAINPAGE`, make its first Markdown heading a level 1 heading +> (`# ...`). An HTML `

` does not count. Starting with a level 2 or lower Markdown heading can cause Doxygen to +> place the main page's sections beneath the next Markdown page in the navigation tree. 1. Add this repository as a submodule to your project. @@ -43,7 +53,7 @@ INPUT += ../third-party/doxyconfig/docs/source_code.md ``` -6. Optionally, copy the `.readthedocs.yaml` file to the root of your project. +6. To build the project on Read the Docs, copy `.readthedocs.yaml` to the root of your project.