Doxygen Markdown Links to main page do not work

Question

I am creating a documentation using Doxygen 1.8.17 which has several overview pages written in Markdown. For this I am creating a main page and a few other pages, which will contain links between each other like shown in this post and in the doxygen documentation.

My problem is, that links from the other pages to the main page (README.md) don't work, while links from the main page to the other pages work and links between other pages work.

I compiled the example using a defauld doxyfile (doxygen -g followed by doxygen Doxyfile). While compiling, doxygen complains about unresolved references ( DoxyMinimalExample/otherpage.md:6: warning: unable to resolve reference to 'mainpage' for \ref command)

No link to README.md works. How do I create a link back to the main page? How is the correct name for the \ref command?

Minimal example (all files in the same folder): README.md

# The Main Page {#mainpage}
My Main Page
============

Documentation that will appear on the main page

1. See [the other page](@ref otherpage) for more info.
2. or see @ref md_otherpage for more info.

or
1. See [the third page](@ref thirdpage) for more info.

otherpage.md

# The Other Page {#otherpage}
My other page
============

More detailed Info
1. See [the main page](@ref mainpage) for an overview.
2. See [the main page](@ref #mainpage) for an overview.
3. See [the main page](@ref #README) for an overview.
4. See [the main page](@ref README) for an overview.
5. See [the main page](@ref README.md) for an overview.
6. See [the main page](README.md) for an overview.
7. See [the main page](@ref md_README) for an overview.
8. See [the main page](@ref md_mainpage) for an overview.
9. See [the main page](md_README) for an overview.
10. See [the main page](md_mainpage) for an overview.
11. See @ref mainpage for an overview.
12. See [the main page](@ref md_README.md) for an overview.
13. See @ref md_README for an overview.
14. See @ref md_README.md for an overview.

or
1. See [the third page](@ref thirdpage) for other info

thirdpage.md

# The Third Page {#thirdpage}
My third page
============

More detailed Info
1. See [the other page](@ref otherpage) for other info

A bit strange, have to check why, but you can refer to the mainpage by means of "index" so e.g. See [the main page](@ref index) for an overview. — albert
Thank you! Somehow I did not think of that. That solves my usecase but leaves the mystery.... — Elbrecht85
It is indeed a bit of a mystery, maybe worth to create an issue at github.com/doxygen/doxygen/issues/new — albert

albert albert · Accepted Answer · 2020-01-14T14:02:29

It is a bit strange that a page with anchor {#mainpage} cannot be referenced in doxygen and one has to use 'index' as reference.

I've just pushed a proposed patch to github (pull request 7511, https://github.com/doxygen/doxygen/pull/7511) to overcome this problem.

EDIT: Code of the pull request has been integrated in master on github

Doxygen Markdown Links to main page do not work

1 Answers