Re: [Doxygen-users] Creating links in and between Markdown files/pages

[Dimitri v. H. <do...@gm...>]

Hi Paul,

On 19 Jun 2014, at 13:28 , Paul Anton Letnes <pa...@le...> wrote:

> Greetings, documentation enthusiasts.
> 
> I have created a simple doxygen example (see attached file). What I want to make (for now) is a "User Manual" style document. Later I will include source code documentation, but for now, I am looking to implement the current user manual in Markdown + doxygen. In this document, it would be nice to be able to create links both inside a single page, and between pages. However, I can't see a way of doing this in the Markdown syntax supported by Doxygen.
> 
> I am perfectly willing to accept something along the lines of a "\page foo" or "\label foo" directive (i.e. syntax outside Markdown)  once per file/top section header, but it would be beneficial to keep this doxygen-specific stuff to an absolute minimum, as we hope to use the same Markdown source for several purposes.
> 
> Links are essential for HTML output. For LaTeX/PDF we can live without, but it sure would be a great thing to have there, too. Can anyone help me with this?

There are two ways:

1) If you have a page with header label, i.e. 

# Tips and tricks for formatting Markdown correctly {#tips}

you can simply use "@ref tips".

Note that the subsequent sections have to be at the same level as the title in order 
for them to be rendered as sections within the page (you can call this a bug):

# Quotes {#quo}

...

# Links {#links}

...

Then you can refer to the sections using @ref quo and @ref links.

2) If do not have a header label for a page, i.e.

# Tips and tricks for formatting Markdown correctly

so without the {#...} part, then you have to use @ref md_<page_base_name> to link to the page, i.e. @ref md_tips and @md_introduction.

I hope this helps.

Regards,
  Dimitri