0

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.

Andrew Cottrell
  • 3,312
  • 3
  • 26
  • 41

1 Answers1

1

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

albert
  • 8,285
  • 3
  • 19
  • 32
  • Unfortunately this doesn't seem to be 100% working. Using that format, the second-level header text ("Header 2") disappears from the main page. Tested in Firefox and Edge. If I remove the labels then the second-level headers reappear. – Andrew Cottrell Apr 28 '20 at 17:24
  • Just updated to 1.8.13. Still no luck. Adding the label causes the second-level header text to disappear. – Andrew Cottrell Apr 28 '20 at 17:51
  • Haha my bad. I did a full upgrade, but I guess 1.8.13 is still the latest for my test environment. – Andrew Cottrell Apr 28 '20 at 17:54
  • Maybe give 1.8.18 a try (download the sources and compile, isn't really a big issue) or do it with the current master. Which OS are you using? – albert Apr 28 '20 at 17:56
  • Looks like I'm running into this error. The proposed workaround aren't working for me though. https://stackoverflow.com/questions/13648124/header-label-in-doxygen-markdown-page-makes-header-title-disappear – Andrew Cottrell Apr 28 '20 at 18:05
  • Those examples there are all about old versions as well, since those versions a lot of tings have changed. Maybe best to create a small MWE showing your problem (including settings in your doxygen configuration file compared to the default doxygen configuration file). Do you get warnings with your example? – albert Apr 28 '20 at 18:27
  • The minimal example is to create a .md file (e.g. tmp.md) with only the contents you posted above, use that .md file in the default generated Doxyfile for INPUT and USE_MDFILE_AS_MAINPAGE, and run doxygen. Tested on Ubuntu with doxygen 1.8.11 and Ubuntu under WSL with doxygen 1.8.13. – Andrew Cottrell Apr 28 '20 at 19:23
  • The warnings are of the form: "warning: found subsection command outside of section context!" – Andrew Cottrell Apr 28 '20 at 19:25
  • With 1.8.13 I get the warnings plus on th eain page just the "Header 1", When using 1.8.18 I don't get a warning and I do see "Header 1" and "Heading 2". It looks like that the problem is fixed from 1.8.16 and hiher. – albert Apr 28 '20 at 19:54
  • Ok, good to know. I'll work around the issue until the Ubuntu packages get updated. Thanks for your help albert! – Andrew Cottrell Apr 28 '20 at 19:57