36

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?

izb
  • 50,101
  • 39
  • 117
  • 168
  • 1
    Does the doxygen command \ref help at all? It works for me for linking to doxygen \section headers in other markdown pages, but I'm unsure if that helps your specific requirements re github. – Cheeseminer Oct 31 '13 at 11:46

4 Answers4

24

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)
adib
  • 8,285
  • 6
  • 52
  • 91
  • 2
    Note that doxygen *1.8.7* is important, Centos 7 still comes with 1.8.5 where the third option wont work. It has just been over three years, better keep doxygen stable. – ted Feb 07 '18 at 14:30
  • The first and second methods to link to a separate page result in `@ref md_subdir_MyOtherPage "Go to this page"` appearing in the output page (literally, the browser shows it this way; no hyperlink is generated). The third method works fine when I link to a section on the same page (the link can also be typeset as `[Go to this page](#MyOtherPageName)`), but the same problem appears as with the first two methods if the link refers to another page. – Ruslan May 11 '22 at 12:45
  • With Doxygen 1.9.1/1.9.7 the two first methods did not work for me, but the third worked fine. – Werner Henze Aug 24 '23 at 12:00
8

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.

kyrofa
  • 1,759
  • 1
  • 14
  • 19
  • 1
    This fixed the problem for me in my case I have folder doc with doxyfile and markdown folder. Therefore I have to write `[file](markdown/file.md)`. Thank you! – Javi Mar 03 '15 at 09:54
  • 2
    If I am not wrong, trying to reference [some](link/to/file.md) from another .md file that is not relative to where Doxygen is run breaks everything for Gitlab (but not for Doxygen). So this is fundamentally incompatible with having the same links for md files in a repo viewable and in Doxygen at the same time. – Germán Diago Jan 25 '19 at 01:48
2

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)
rockgecko
  • 4,127
  • 2
  • 18
  • 31
  • 4
    I use 1.8.7, and it still does not work. It always refers to the source of the .md file (in html), not the rendered (html) page. it does not matter whether I use `@ref` or `[here](documentation.md)`. Is there a solution for this? – verpfeilt Jun 19 '14 at 22:01
  • 1
    Got it working in 1.8.11. Possible gotchas: the linked page _must_ be included in INPUT, and the linked page _must not_ contain a header label (e.g. `# Page {#page}`) – Conrado Jun 29 '18 at 13:35
0

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.

KRoy
  • 1,290
  • 14
  • 10