Add first-level headings to navmenu #239
Conversation
|
In documentation circles, a small amount of selective redundancy is considered acceptable (more so than in coding circles)... So it wouldn't be too bad if the first heading was also used elsewhere. But this solution is also fine -- particularly if added to the really fine manual. |
| hs = filter(e -> isa(e, Base.Markdown.Header{2}), page.elements) | ||
| map(hs) do e | ||
| hs = filter(enumerate(page.elements)) do _ | ||
| i, e = _ |
There was a problem hiding this comment.
Can i and e have more descriptive names?
Yes, that seems reasonable to me. |
Add first-level headings to the navigation menu. The only exception is when the very first block of a page is a first-level heading -- in this case that particular heading is ignored. This is consistent with how the headings are usually used, with the first heading being the page title. The `<li>` tags of the first-level headers have the class `.toplevel` attached to them, so that we can style them in the CSS. Fixes #225.
To be consistent with the sidebar change, where we don't display the first <h1>, we should also only use the <h1> tag to guess the page title when it is the very first block of the Markdown file.
|
I think we should treat the page outline consistently, both in the sidebar and when guessing a page title. So I've added a change that we'd only use the very first Assuming it looks good, I'd propose that we would only backport the first commit -- the second commit changes the behavior of Documenter. |
It only changes the behaviour of the HTML output, correct? If so then we can get away with changing it in a point release since we've explicitly stated that it is experimental at this point. Probably better to change it sooner rather than later anyway, otherwise people will end up relying on it if we leave it too long. |
|
(Also, LGTM, so merge whenever you're ready @mortenpi.) |
Add first-level headings to the navigation menu. The only exception is
when the very first block of a page is a first-level heading -- in this
case that particular heading is ignored. This is consistent with how
the headings are usually used, with the first heading being the page
title.
The
<li>tags of the first-level headers have the class.toplevelattached to them, so that we can style them in the CSS.
Fixes #225.
@cormullion and @MichaelHatherly: What I am wondering is whether the behavior that a
<h1>is a page title if and only if it is the very first block of a page is reasonable. Also, should we go with this, I guess we should also change thepagetitlefunction, so that only the very first block would be used to automagically determine a page title for the nav.menu?We could also maybe use a small doc. note on this.