53

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.

Adam L. S.
  • 693
  • 1
  • 6
  • 12
  • 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. – pconcepcion Nov 16 '12 at 19:50
  • 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. – Ivan Jan 24 '13 at 17:55
  • 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. – Rob Cranfill Dec 05 '13 at 22:15
  • Does this happen, if you remove your `# Eat my shorts…` but leave a newline in there, like `\n # TripWrap:…`? (Just bluffing.) – Adam L. S. Dec 08 '13 at 16:49

2 Answers2

137

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.

doxygen
  • 13,368
  • 2
  • 36
  • 33
  • 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. – Adam L. S. Nov 19 '12 at 19:22
  • 1
    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? – Codie CodeMonkey Mar 04 '13 at 23:43
  • 1
    This method doesn't work for me on 1.8.5. Any ideas? – xuhdev Dec 09 '13 at 02:07
  • Does not work for me (1.8.4 from Ubuntu 13.10 Repositories) either… – NobbZ Mar 08 '14 at 13:42
  • 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? – Lukas Kalinski Nov 16 '16 at 12:36
  • Does not seem to work for doxygen 1.8.5 distributed with CentOS 7. – phoenix Apr 27 '17 at 13:43
  • 2
    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. – davidA Aug 05 '17 at 00:05
  • 1
    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`. – Avamander Aug 15 '17 at 10:50
  • I had to add \mainpage to the README.md file to get it to be recognized as the main page – JBaczuk Feb 02 '18 at 01:15
  • 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? @doxygen – Rimmel May 06 '18 at 21:23
  • @doxygen 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. – jdc Aug 08 '18 at 02:47
14

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.

Masked Man
  • 1
  • 6
  • 35
  • 77
  • 1
    This one did not worked for me. This was my first attempt though. how is your doxyfile is configured? – Adam L. S. Nov 19 '12 at 19:01
  • @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. – Masked Man Nov 26 '12 at 15:36
  • @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. – Masked Man Nov 28 '12 at 13:49
  • 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. – Adam L. S. Nov 29 '12 at 23:12
  • 2
    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. – Masked Man Nov 30 '12 at 09:46