Can doxygen link from C source code back to sections of a .md Markdown file?

0
votes

I have seen that doxygen can use a .md (Markdown) file as its output documentation main page via the config file setting USE_MDFILE_AS_MAINPAGE. I have also seen that function names in the .md file (e.g. myfunc()) will link to the documentation for that function.

Is there a way to link back from the source code (e.g. a C function header) to sections of the .md file?

Currently I am describing several product-related concepts in the source code using the doxygen @page special command, and I am able to have other source code refer back to these pages via the @ref special command. For example, I can create @page concept My Concept and link to it from elsewhere via @ref concept. But I would prefer to document these concept sections in a separate documentation-focused file instead of in a source code file, so moving them to a .md file seems like the logical approach.

UPDATE: albert's answer below probably should work, but with the versions of doxygen I tested (1.8.11 and 1.8.13) the proposed solution has the following problems:

  1. Level 2 headers (i.e. those starting with ##) that include a header ID attribute (e.g. {#label2}) no longer appear in the generated doxygen output, and generate the output: "warning: found subsection command outside of section context!" This is apparently a known bug. A workaround that works for me is to duplicate the header, with one line including the header ID attribute and the other excluding it. For example:

    ## Header 2 {#label2}

    ## Header 2

  2. Code that links back to these level 2 headers via @ref label2 do not appear to link back to the specified section but rather to the head of the page containing the section, which is significantly less useful if the page is long and/or contains multiple sections.

UPDATE 2: Apparently issue 1 above is fixed in doxygen version 1.8.16 and later.

1
markdowndoxygen
Which doxygen vesrion? – albert
1.8.13 currently – Andrew Cottrell
Current version is 1.8.18, but my answer should most likely also work with 1.8.13 – albert

1 Answers

1
votes

With sections / pages etc. in markdown one can also specify an id attribute like:

Header 1 {#labelid}
========

## Header 2 ## {#labelid2}

these are extension and described in the manual under: http://doxygen.nl/manual/markdown.html#md_header_id. These id attributes can be referenced by e.g. \ref