-
-
Notifications
You must be signed in to change notification settings - Fork 7.7k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Heading levels in Markdown table of contents #1778
Comments
I have not read this in detail, but we get the ToC from https://github.com/russross/blackfriday -- so maybe it is better to discuss it there. |
I am affected by this odd behaviour too. The way The issue here is that blackfriday spits out a bunch of hard coded HTML tags, and then Hugo wrap them in a way that is neither valid HTML code. A solution is quite simple: don't give users a preformatted |
@Parent5446 and @Dr-Terrible, |
The bottom line of this is: The ToC should not be HTML, it should be a datastructure that people can do with as they please. |
Okay, for some reason, even though I'm putting this on hold for the time being for I'd prefer to test it with a newer jekyll version (and dependencies), which would take some more time. I found that the level4 subsections are not that large, so we could get without links there. What do you think, guys? Cheers, |
I've written a little tool that removes the unnecessary level of nesting from the table of contents. You can run it, after Hugo has generated the contents in the "public" folder. |
I'm running into an issue that may be related. It seems that when I have a lower level tag i.e. an H6 appearing first in my content before an H5, a TOC is rendered at the start of my content, without my explicitly including a .TableOfContents tag. What I mean is, if my content looks like:
Then all is right with the world, and no TOC gets generated. But if it looks like this:
Then I get the garbled TOC HTML appearing arbitrarily at the start of my content. It doesn't even have the "TableOfContents" ID; it's just a naked NAV tag. Seems like a bug... |
This issue has been automatically marked as stale because it has not been commented on for at least four months. The resources of the Hugo team are limited, and so we are asking for your help. If this is a bug and you can still reproduce this error on the If this is a feature request, and you feel that it is still relevant and valuable, please tell us why. This issue will automatically be closed in four months if no further activity occurs. Thank you for all your contributions. |
Note/Update: This issue is marked as stale, and I may have said something earlier about "opening a thread on the discussion forum". Please don't. If this is a bug and you can still reproduce this error on the latest If this is a feature request, and you feel that it is still relevant and valuable, please tell us why. |
This issue is still unresolved. |
Any news on this? It appears to be still unresolved. |
I found this open issue when trying to figure out why Hugo's snippet from <!-- ignore empty links with + -->
{{ $headers := findRE "<h[1-6].*?>(.|\n])+?</h[1-6]>" .Content }}
<!-- at least one header to link to -->
{{ $has_headers := ge (len $headers) 1 }}
<!-- a post can explicitly disable Table of Contents with toc: false -->
{{ $show_toc := (eq $.Params.toc true) }}
{{ if and $has_headers $show_toc }}
<div class="table-of-contents toc bd-callout">
<!-- TOC header -->
<h4 class="text-muted">Table of Contents</h4>
{{ range $headers }}
{{ $header := . }}
{{ range first 1 (findRE "<h[1-6]" $header 1) }}
{{ range findRE "[1-6]" . 1 }}
{{ $next_heading := (int .) }}
<!-- generate li array of the proper depth -->
{{ range seq $next_heading }}
<ul class="toc-h{{ . }}">
{{end}}
{{ $base := ($.Page.File.LogicalName) }}
{{ $anchorId := ($header | plainify | htmlEscape | urlize) }}
{{ $href := delimit (slice $base $anchorId) "#" | string }}
<a href="{{ relref $.Page $href }}">
<li>{{ $header | plainify | htmlEscape }}</li>
</a>
<!-- close list -->
{{ range seq $next_heading }}
</ul>
{{end}}
{{end}}
{{end}}
{{ end }}
</div>
{{ end }} Here is how I have it working to render TOCs for Posts: <div class="content">
{{ partial "banner" . }}
{{ partial "table-of-contents" . }}
<!-- supports emoji -->
{{ .Content | emojify }}
</div> |
Once we have #1778, we can more easily provide the TOC as a data structure, using access to the syntax tree, or perhaps writing a new renderer to build during parsing. |
@mikeblum thank you! |
@mikeblum thanks a lot!
Also, it does not work with apostrophes. Both href and title do not work. for example I am not a go expert so I cannot help. |
@alexislg2 The last two functions are incorrect. Here are the relevant changes to get the partial @mikeblum posted working correctly:
|
I implemented the toc as a partial using code from above, but the logic of the code produced markup that was invalid and not semantically sound. So I rewrote it like so: https://gist.github.com/skyzyx/a796d66f6a124f057f3374eff0b3f99a This version intentionally only looks for Feel free to re-adjust the regexes if you want a broader spectrum of headers. |
…i.e. h1) but lower levels (h2, h3, ...) it seems Hugo/Blackfriday don't want to fix it: gohugoio/hugo#1778
In case any one is interested, I just wrote a short JS script to remove the non-existent You can include the script via something like Here is an example. If your eyes are quick enough, you can actually see the first |
@skyzyx Thanks for sharing. I'm implement this in my Hugo blog on GitLab under @yihui Thanks for your JavaScript, even though it works only if there's more than one section. I've adapted your script to Beautiful Hugo and published it on GitLab snippet. // Copyright (c) 2017 Yihui Xie & 2018 Vincent Tam under MIT
(function() {
var toc = document.getElementById('TableOfContents');
if (!toc) return;
do {
var li, ul = toc.querySelector('ul');
if (ul.childElementCount !== 1) break;
li = ul.firstElementChild;
if (li.tagName !== 'LI') break;
// remove <ul><li></li></ul> where only <ul> only contains one <li>
ul.outerHTML = li.innerHTML;
} while (toc.childElementCount >= 1);
})(); |
here's another twist on collapsing empty heading levels using hugo static generation vs recurring javascript overhead... the gist is to use string replace to target the empty levels... there's no conditional looping in hugo templates yet so i just applied the basic approach 3 times which covers all my markup scenarios note the pattern on closing tag carriage returns is slightly different than opening tags
|
This commit adds the fast and CommonMark compliant Goldmark as the new default markdown handler in Hugo. If you want to continue using BlackFriday as the default for md/markdown extensions, you can use this configuration: ```toml [markup] defaultMarkdownHandler="blackfriday" ``` Fixes gohugoio#5963 Fixes gohugoio#1778
This commit adds the fast and CommonMark compliant Goldmark as the new default markdown handler in Hugo. If you want to continue using BlackFriday as the default for md/markdown extensions, you can use this configuration: ```toml [markup] defaultMarkdownHandler="blackfriday" ``` Fixes gohugoio#5963 Fixes gohugoio#1778 Fixes gohugoio#6355
This commit adds the fast and CommonMark compliant Goldmark as the new default markdown handler in Hugo. If you want to continue using BlackFriday as the default for md/markdown extensions, you can use this configuration: ```toml [markup] defaultMarkdownHandler="blackfriday" ``` Fixes gohugoio#5963 Fixes gohugoio#1778 Fixes gohugoio#6355
This commit adds the fast and CommonMark compliant Goldmark as the new default markdown handler in Hugo. If you want to continue using BlackFriday as the default for md/markdown extensions, you can use this configuration: ```toml [markup] defaultMarkdownHandler="blackfriday" ``` Fixes gohugoio#5963 Fixes gohugoio#1778 Fixes gohugoio#6355
This commit adds the fast and CommonMark compliant Goldmark as the new default markdown handler in Hugo. If you want to continue using BlackFriday as the default for md/markdown extensions, you can use this configuration: ```toml [markup] defaultMarkdownHandler="blackfriday" ``` Fixes gohugoio#5963 Fixes gohugoio#1778 Fixes gohugoio#6355
This commit adds the fast and CommonMark compliant Goldmark as the new default markdown handler in Hugo. If you want to continue using BlackFriday as the default for md/markdown extensions, you can use this configuration: ```toml [markup] defaultMarkdownHandler="blackfriday" ``` Fixes gohugoio#5963 Fixes gohugoio#1778 Fixes gohugoio#6355
This commit adds the fast and CommonMark compliant Goldmark as the new default markdown handler in Hugo. If you want to continue using BlackFriday as the default for md/markdown extensions, you can use this configuration: ```toml [markup] defaultMarkdownHandler="blackfriday" ``` Fixes gohugoio#5963 Fixes gohugoio#1778 Fixes gohugoio#6355
This commit adds the fast and CommonMark compliant Goldmark as the new default markdown handler in Hugo. If you want to continue using BlackFriday as the default for md/markdown extensions, you can use this configuration: ```toml [markup] defaultMarkdownHandler="blackfriday" ``` Fixes gohugoio#5963 Fixes gohugoio#1778 Fixes gohugoio#6355
This commit adds the fast and CommonMark compliant Goldmark as the new default markdown handler in Hugo. If you want to continue using BlackFriday as the default for md/markdown extensions, you can use this configuration: ```toml [markup] defaultMarkdownHandler="blackfriday" ``` Fixes gohugoio#5963 Fixes gohugoio#1778 Fixes gohugoio#6355
This commit adds the fast and CommonMark compliant Goldmark as the new default markdown handler in Hugo. If you want to continue using BlackFriday as the default for md/markdown extensions, you can use this configuration: ```toml [markup] defaultMarkdownHandler="blackfriday" ``` Fixes gohugoio#5963 Fixes gohugoio#1778 Fixes gohugoio#6355
This commit adds the fast and CommonMark compliant Goldmark as the new default markdown handler in Hugo. If you want to continue using BlackFriday as the default for md/markdown extensions, you can use this configuration: ```toml [markup] defaultMarkdownHandler="blackfriday" ``` Fixes gohugoio#5963 Fixes gohugoio#1778 Fixes gohugoio#6355
This commit adds the fast and CommonMark compliant Goldmark as the new default markdown handler in Hugo. If you want to continue using BlackFriday as the default for md/markdown extensions, you can use this configuration: ```toml [markup] defaultMarkdownHandler="blackfriday" ``` Fixes gohugoio#5963 Fixes gohugoio#1778 Fixes gohugoio#6355
This commit adds the fast and CommonMark compliant Goldmark as the new default markdown handler in Hugo. If you want to continue using BlackFriday as the default for md/markdown extensions, you can use this configuration: ```toml [markup] defaultMarkdownHandler="blackfriday" ``` Fixes gohugoio#5963 Fixes gohugoio#1778 Fixes gohugoio#6355
This commit adds the fast and CommonMark compliant Goldmark as the new default markdown handler in Hugo. If you want to continue using BlackFriday as the default for md/markdown extensions, you can use this configuration: ```toml [markup] defaultMarkdownHandler="blackfriday" ``` Fixes gohugoio#5963 Fixes gohugoio#1778 Fixes gohugoio#6355
This commit adds the fast and CommonMark compliant Goldmark as the new default markdown handler in Hugo. If you want to continue using BlackFriday as the default for md/markdown extensions, you can use this configuration: ```toml [markup] defaultMarkdownHandler="blackfriday" ``` Fixes gohugoio#5963 Fixes gohugoio#1778 Fixes gohugoio#6355
This commit adds the fast and CommonMark compliant Goldmark as the new default markdown handler in Hugo. If you want to continue using BlackFriday as the default for md/markdown extensions, you can use this configuration: ```toml [markup] defaultMarkdownHandler="blackfriday" ``` Fixes gohugoio#5963 Fixes gohugoio#1778 Fixes gohugoio#6355
This commit adds the fast and CommonMark compliant Goldmark as the new default markdown handler in Hugo. If you want to continue using BlackFriday as the default for md/markdown extensions, you can use this configuration: ```toml [markup] defaultMarkdownHandler="blackfriday" ``` Fixes gohugoio#5963 Fixes gohugoio#1778 Fixes gohugoio#6355
This commit adds the fast and CommonMark compliant Goldmark as the new default markdown handler in Hugo. If you want to continue using BlackFriday as the default for md/markdown extensions, you can use this configuration: ```toml [markup] defaultMarkdownHandler="blackfriday" ``` Fixes gohugoio#5963 Fixes gohugoio#1778 Fixes gohugoio#6355
This commit adds the fast and CommonMark compliant Goldmark as the new default markdown handler in Hugo. If you want to continue using BlackFriday as the default for md/markdown extensions, you can use this configuration: ```toml [markup] defaultMarkdownHandler="blackfriday" ``` Fixes gohugoio#5963 Fixes gohugoio#1778 Fixes gohugoio#6355
This commit adds the fast and CommonMark compliant Goldmark as the new default markdown handler in Hugo. If you want to continue using BlackFriday as the default for md/markdown extensions, you can use this configuration: ```toml [markup] defaultMarkdownHandler="blackfriday" ``` Fixes gohugoio#5963 Fixes gohugoio#1778 Fixes gohugoio#6355
This commit adds the fast and CommonMark compliant Goldmark as the new default markdown handler in Hugo. If you want to continue using BlackFriday as the default for md/markdown extensions, you can use this configuration: ```toml [markup] defaultMarkdownHandler="blackfriday" ``` Fixes gohugoio#5963 Fixes gohugoio#1778 Fixes gohugoio#6355
This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs. |
So I'm not sure if this is at all possible, or what the best way would be to do this, but we're having some issues using the
.TableOfContents
variable in templates.There are a couple of points:
<h1>
tag per section root.<body>
-level,<h1>
tag generated in the layout template using the.Title
attribute of the page. (It works better semantically, rather than having the title in two places.).TableOfContents
, sensibly, only renders navigation for the headers in the actual content..TableOfContents
always treats<h1>
as top-level, even if there are no<h1>
-level headers.Because of this, if you comply with (1) and implement (2), and thus only have
<h2>
or lower headers in your content, the generated table of contents contains an empty top-level<nav>
as a result of (3) and (4).Example table of contents:
This messes with the page semantically since now the navigation has an empty top-level. The way I see it there are two ways to fix this:
<h2>
as top-level headers if there is no<h1>
in the content.I'm not sure if there is currently an undocumented workaround to implement either of these solutions. But if there isn't, would there be a way to allow for using either of the two solutions to achieve a more semantic table of contents?
The text was updated successfully, but these errors were encountered: