How do I link between markdown documents in doxygen?

Question

I have a project with a set of markdown pages that are interlinked with links such as

[Go to this page](subdir/MyOtherPage.md)

The pages all get picked up by doxygen and appear in the output, but the links are not altered to point to their new html renditions.

I could change the links to point to the html pages, but my project is hosted on github and then those links would become broken since github supports linking between markdown pages automatically.

I can't see anything in the doxygen documentation about supporting links other than external ones. Is there any way to make doxygen produce an HTML link from a markdown one?

Answer 1

As per Doxygen 1.8.7 there are three ways to do this:

• Use a standard markdown hyperlink as described in your original question.
• Use a @ref and prefix the target with md_ along with any subdirectories.
• Name the page and use @ref to refer to the name.

The first method is straightforward and this will also work without Doxygen (e.g. when browsing your code repository on Github).

[Go to this page](subdir/MyOtherPage.md)

Whereas the second method you'll need to link it like this:

[Go to this page](@ref md_subdir_MyOtherPage)

Apparently this also is the way prescribed by the Doxygen's primary author.

Lastly in the third method you'll need to have a name for the target page and then link to that name. Example:

In MyOtherPage.md have this as the header

# My Other Page Title {#MyOtherPageName}

then link it like so

[Go to this page](@ref MyOtherPageName)

Answer 2

Regular-old Markdown links are handled as of Doxygen 1.8.6, e.g. [link text](docs/page.md). This works a little wonky, though-- the URL must be relative from the Doxygen working directory (i.e. not the directory of the Doxyfile or the .md file, but the directory from which Doxygen is RUN). If you notice that clicking the link shows raw Markdown instead of rendered HTML, it means your URL is not relative from Doxygen's working directory.

Answer 3

This feature was added in Doxygen 1.8.6 (Dec 2013)

Allow @ref to unlabeled markdown page by name, i.e. @ref mypage.md
Allow links to other markdown pages of the form [link text](page.md)

You might need to incldue the documentation directory in the link for it to work, eg

[link text](docs/page.md)

Answer 4

The following steps may solve the problem,

• set STRIP_FROM_PATH to Doxyfile directory. There is a problem with relative path while linking the markdown files.

• append the following code in doxygen source file src/docparser.cpp at 2438 line number containing code pd = Doxygen::pageSDict->find(target); (if it is not there already). It fixes the markdown file searching in the page-list.

  if(pd == 0 && lang == SrcLangExt_Markdown) {pd = Doxygen::pageSDict->find(markdownFileNameToId(target));}

• Finally compile the doxygen and try again.

It worked for me.