Use the README.md file as main page in Doxygen

Question

The documentation of Doxygen states, that I can use PHP Markdown Extra title labelling in a markdown file, but neither

# Main Page # {#mainpage}

nor

# Main Page # {#index}

works, but the label is not present in the output as plain text either. This is the very first line BTW.

Also I cannot reference to that page neither with the above labels, neither with the name of the file.

I also have a main.dox file that contains a \mainpage special command, but I also tried all the above with removing one slash before them (to make it only two).

I'm using Doxygen 1.8.2 (downloaded) and 1.8.1.1 (from MacPorts) for the task.

How can I achieve this then?

Also, how can I mark a markdown file as part of a specific language?

EDIT: i have enabled markdown support, and the file appears in the referenced pages.

Flem

I'm having some similar problem... I'd like to have my README.md included on my Main Page, but I haven't figured out yet if it's possible. – Cadaverine

I also having a hard time to include a README.md to my doxygen configuration. Just not working at all, and with doxygen 1.8 and use_markdown, of course. – Idonah

As far as I can tell, doxygen (I'm using 1.8.5) simply ignores whatever you put on that first line. So my 'mainpage.md' starts with (note that this is two lines; you can't have multiline comments?) # Eat my shorts, Doxygen! This header line is ignored!\n # TripWarp: Detergent Motives Incomplete With Indians and then I get my desired top-level heading. – Hydrogeology

Does this happen, if you remove your # Eat my shorts… but leave a newline in there, like \n # TripWrap:…? (Just bluffing.) – Flem

Answer 1

In the next release of doxygen (1.8.3) I plan to introduce a new configuration option USE_MDFILE_AS_MAINPAGE which can be used to specify a markdown page that is to be used as the main page. Then you can configure doxygen as follows:

INPUT                  = README.md other_sources
USE_MDFILE_AS_MAINPAGE = README.md

and it will work regardless of page's headings.

Accomplish

And it will be a wonderfull christmas gift. ;) I don't like to compile prereleases, because they more likely to be broken, but if you release it this soon (compared to how slow I develope) than it might even worth for me to wait for the release. But if I need it sooner, then I will compile it. -- I wish I could accept two answers. – Flem

This functionality works well now (1.8.3), EXCEPT that the names of the .md files are showing up in the tree view. Any idea why this would be? – Cannikin

This method doesn't work for me on 1.8.5. Any ideas? – Pridemore

Does not work for me (1.8.4 from Ubuntu 13.10 Repositories) either… – Elianore

Would be nice to have the optional possibility to use a readme file on a per-directory basis, i.e. "In this directory you find... the conventions are...". Or can you do that already? – Lott

Does not seem to work for doxygen 1.8.5 distributed with CentOS 7. – Intended

This worked for me (doxygen 1.8.13) however I had to put the README.md file as the first entry in my INPUT list. Even though it was the first (and only) .md file, if it wasn't the first entry it would generate a "Related Pages" section instead of replacing the main page. – Mailman

Make sure you haven't excluded the README.md you wish to use and use ./README.md (or other relative path) instead of just README.md. – Francesco

I had to add \mainpage to the README.md file to get it to be recognized as the main page – Geraud

I'm using doxygen with USE_MDFILE_AS_MAINPAGE = README.md and it generates the appropriate HTML, however, I would also still like to use the same README.md for GitHub on the project's page. As it stands now, If I want to use [TOC] and labels for sections ({#secid}), I get output like this on the GitHub project page: My Header Text {#secid} I just want 'My Header Text' without the rendered section label, and I'm having a hard time finding ways around it. Any tips? @Accomplish – Freberg

@Accomplish After hours of searching, I stumbled upon this answer. Thank you! I really think you should include a reference to USE_MDFILE_AS_MAINPAGE under the documentation for include and includedoc in the Special Commands page of your documentation - I think it will help many users in the future. – Neogothic

Answer 2

Try the following instead to mark the title as a level 1 header:

Main Page {#mainpage}
=========

With doxygen 1.8.2, this makes the page as the index.html page for me.

The doxygen document does state that starting a line with a single # declares a level 1 header, but it seems to be not working for me either.

Madiemadigan

This one did not worked for me. This was my first attempt though. how is your doxyfile is configured? – Flem

@AdamL.S. Let's start with: MARKDOWN_SUPPORT = YES. Do you have this enabled? I don't see any other setting being relevant, but I could be wrong about that. Sorry, I didn't get any notification for this comment, hence the delay in responding. – Madiemadigan

@AdamL.S. Well, then I guess the only other difference between your settings and mind could be that I have explicitly set the following: FILE_PATTERNS = *.markdown I think it should not make any difference, but give it a try. – Madiemadigan

If I recall it right, both *.md and *.markdown are set in FILE_PATTERNS by default for the most recent version, (with the doxywizard at least) and of course, you need to set those as well to make it work. – Flem

That is right, but for me, doxygen 1.8.2 ignored both *.md and *.markdown, so I tried putting into FILE_PATTERNS explicitly, and it worked. – Madiemadigan

With doxygen 1.9, tested with Doxyfile 1.9.6 schema, MARKDOWN_SUPPORT is set at "YES" by default. Also, the default value for FILE_PATTERNS includes .md and .markdown. – Iroquois