[prev in list] [next in list] [prev in thread] [next in thread] 

List:       doxygen-users
Subject:    Re: [Doxygen-users] Markdown Header Ids Bug?
From:       Sascha Zelzer <s.zelzer () dkfz-heidelberg ! de>
Date:       2012-03-26 20:47:22
Message-ID: 4F70D5DA.4090901 () dkfz-heidelberg ! de
[Download RAW message or body]

Hi Dimitri,


On 03/26/2012 08:50 PM, Dimitri Van Heesch wrote:
> Hi Sascha,
>
> On Mar 26, 2012, at 17:30 , Sascha Zelzer wrote:
>> Hi,
>>
>> I absolutely love the Doxygen Markdown support - thanks for that!
>>
>> However, I have some troubles getting header ids to work
>> (http://www.stack.nl/~dimitri/doxygen/markdown.html#md_header_id).
>>
>> For a markdown text like:
>>
>> ~~~~~~~~~~~~~~~~~~~~~~~~
>> Level 1 Header {#Header1}
>> =======
>>
>> ## Level 2 Header ##    {#Header2}
>>
>> Text
>> ~~~~~~~~~~~~~~~~~~~~~~~~
>>
>> The "Level 2 Header" section does not appear in the output (without the
>> header id it does). Also using dashes (---) instead of the hash sign (#)
>> does not work.
> The problem is that the Level 1 header is used as the page title, basically
> making it a level0 header, which is then followed by an unexpected level 2 header.

Thanks a lot for your explanation, I think I get what you mean. The 
reason why I thought this is maybe a bug is because the html output was 
as expected without the header ids. I am mainly thinking about related 
pages written in markdown, so I may not be aware of all formatting 
issues here.
> I plan to correct this by lowering the levels of all sections after the title
> in such case, until another level 1 header is found at which point the
> level correction is disabled.

So, without the header ids, the example above produces <h2> elements for 
each "## Level 2 Header ##", just like the \section command (this is 
exactly what I would have assumed). With the header ids, parsing seems 
to behave differently.

> So
> ~~~~~~~~~~~~~~~~~~~~~~~
> Level 1 rendered as page title (level 0)
> =======
>
> ## Level 2 rendered as level 1
>
> # Level 1 rendered as level 1 since we can't go lower anymore
>
> ## Level 2 rendered as level 2 since the level correction has been disabled
> ~~~~~~~~~~~~~~~~~~~~~~~~
>
> Let me know if you have a better idea.
> Alternatives I could think of is to repeat the level 1 header after the page title,
> or breaking the Markdown page into multiple parts, each starting with a level 1 header.

Personally, I would be happy without any level changing logic. So:

(# Level 1 #) -> (<h1> OR <div class="title"> if it is the first level 1 
header)
(## Level 2 ##) -> (<h2> just like \section)
(### Level 3 ###) -> (<h3> just like \subsection)
etc.

With header ids working like already documented. If I would like to have 
an explicit <h1> element at the top of the page, I would just add 
another "# Level 1 #" line.

Does that make sense?

Thanks a lot,

Sascha


------------------------------------------------------------------------------
This SF email is sponsosred by:
Try Windows Azure free for 90 days Click Here 
http://p.sf.net/sfu/sfd2d-msazure
_______________________________________________
Doxygen-users mailing list
Doxygen-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/doxygen-users
[prev in list] [next in list] [prev in thread] [next in thread]