Doxygen: How to reference a README.md file from my main page

Question

I have a project structured like this.

OpenRGB-cppSDK
  doc
    Doxyfile
    main.md  -- Doxygen main page
  examples
    .cpp files with examples
  include
    public .hpp files
  src
    .hpp and .cpp files
  tools
    cli demo
README.md  -- github main page

Now i would like to create a clickable reference to the README.md file and examples directory from the main.md, but i cannot figure out how.

I've added the README.md and examples to the INPUT variable

INPUT                  = ../doc ../include ../src ../README.md ../examples

and i've verified that the FILE_PATTERNS include *.md.

However when i write a sentence into main.md like this

Basic examples are in the \ref README.md, more advanced examples in directory \ref examples.

doxygen tells me it was unable to resolve reference to README.md and examples, even though i can see in its output it found the files

Reading E:/Youda/Projects/OpenRGB-cppSDK/README.md...
Generating docs for page md_E__Youda_Projects_OpenRGB_cppSDK_README...
Preprocessing E:/Youda/Projects/OpenRGB-cppSDK/examples/ContinuouslyUpdateColors.cpp...
Parsing file E:/Youda/Projects/OpenRGB-cppSDK/examples/ContinuouslyUpdateColors.cpp...
...

In the generated web page it shows a button "Related pages" with entry "OpenRGB_cppSDK" that takes me to the README file

but the reference to the README from main.md doesn't work.

I've also tried EXTRACT_ALL = YES, but then what happens is that the main.md page gets a clickable reference to README.md but when i click it, it takes me to a blank page that looks like this

Please, what am i doing wrong?

Answer 1

The version with the markdown type of link does work: [Test with md type](../README.md)

The full project: README.md

# this is the readme file

this is the readme file

doc/main.md

# this is the main file

this is the main file


the test with \\ref no path: \ref README.md

the test with \\ref with path: \ref ../README.md


[Test with md type](../README.md)

doc/Doxyfile

QUIET=YES
INPUT                  = ../doc ../README.md

output in: doc/html/md_main.html

Why doesn't the \ref not work, from the documentation:

24.107 \ref <name> ["(text)"]

Creates a reference to a named section, subsection, page or anchor. For HTML documentation the reference command will generate a link to the section. For a section or subsection the title of the section will be used as the text of the link. For an anchor the optional text between quotes will be used or if no text is specified. For LATEX documentation the reference command will generate a section number for sections or the text followed by a page number if refers to an anchor.

The "../README.md" doesn't constitute a valid name The "README.md" would work when it is a local file (i.e. local to the doc directory).