Interesting suggestion. I didn’t know Blackfriday exposed those commands. But, since we can’t extend Hugo (without forking), we can’t access those APIs, right? Hugo would need to be extended to access those APIs I believe.
So yes, there are two code paths here to explorer:
Option 1) Hugo parse the HTML output (it’s a simple format) to build a collection, and expose that TOC collection to the Page object. Something like:
type TocNode struct {
HasChildren bool
Childrent *TocNode // note recursive property
Depth int // H1, H2, H3 and so on
Anchor string // <a href=""> link
Text string // <a>...</a> inner text
}
Then expose this as a single property of TocNode
on the page struct.
or Option 2) Expose all Blackfriday TOC APi functions in the page’s Frontmatter. And there’s a lot of options here:
That could clutter up the frontmatter. Maybe look at a new struct for this, Toc, and expose all wrapper methods on that, which calls the Blickfriday API before rendering the markdown for that page. That’s one option.
My opinion:
Considering how messy the frontmatter can get with exposing those TOC API functions (the Menu feature is a clear example of how messy the frontmatter can get - it’s just barely livable), I would vote for option 1.
I say this assuming that Blackfriday has been versioned at Hugo (godep, for example). By locking in a version, and writing a few tests using Blackfriday, we can write a parser to parse the HTML into the struct I wrote above. The output of Blackfriday’s TOC structure is simple enough:
<nav id="TableOfContents">
<ul>
<li><h1><a href="#abc">My Text</a></h1></li>
<li>
<ul>
<li><h2><a href="#abc">My Text</a></h2></li>
</ul>
</li>
</ul>
</nav>
Where the contents of <li>
can either be an <h1><a>...
header and anchor combination with text, or another <ul><li><h2><a>
combination signifying a child node of H2, and so on (stop at H6?).
As long as the unit tests pass, that would be good enough for me.
For backwards compability, leave the .TableOfContents
raw HTML currently. Just create a new single property on the Page
struct for the TocNode
, which encloses all child nodes as well. Maybe Page.TocNode
?