Wrapping document sections in <section> tags (code available)

Feature requests
1

I’ve come up with a way to do sticky headings in pure CSS. In order to create a theme with this technique, I need some control over how Zola renders page.content.

I don’t think the templating engine would make this possible.

I went to make a pull request, but the message on github indicated that I should discuss it here first. To prove to myself that it could be done, I put together an implementation on my own fork:

I thought about how this could be made more generic – maybe some people would want to use a tag other than <section>.

I think the ideal would have been to be able to bundle some code for post-processing as part of the theme (so that the needs of each theme don’t have to spill into the main rendering code), but for now that doesn’t seem as feasible.

Open to feedback.

1 Like
2

That’s extremely unlikely to be merged as it’s essentially creating a custom output of CommonMark (never seen before afaik?) for one very very specific use-case.

3

I think semantically it makes sense to group everything under a specific heading in a <section>, so it’s not entirely without reason. Could you clarify what you mean by “custom output of CommonMark”? I see that the spec uses HTML as an example, but I didn’t think that meant there was only one way to convert from CM to HTML.

More generally, would you say that having control over rendering (i.e. page.content) is out-of-scope for Zola? What I’m really hoping for is a way to give themes more flexibility by letting them influence the rendering process.

4

Most people (including me) would assume that the output matches the spec.

More generally, would you say that having control over rendering (i.e. page.content ) is out-of-scope for Zola?

I would say it’s out-of-scope yes

5

I would say it’s out-of-scope yes

Do you still feel the same way?

Output matching the spec only matters if they user hadn’t, in their understanding of the situation, specified otherwise. It would be meaningful to enable users to parse their input differently – say, by automatically invoking semantic HTML rules – as long as the input + spec = output paradigm is set as default and other options are not enforced without user’s say-so.

6

If you need to target a specific heading say at the top of a section you could just specify an ID in the markdown, and target your CSS against the ID.

# Section {#Section}

which would result in HTML output:

<H1 id="Section">
...
</H1>

So your markdown would just specify a known heading to group sections of text.

You could just create a shortcode for your specific need and include it with your template.

Maybe the {{ section() }} template, which users of the template would put in their markdown as required.

Just an idea.

7

My concern is not with having a heading ID – that much I’ve already read about in the manual – or having a specific element in output. My concern is being able to automatically produce semantic HTML without having to manually drive the process at any stage, beyond setting the variable.

2 Likes
9

Creating <section> tags automatically from headings levels in markdown does seem like a valid request to me. There have also been suggestions on how to specify HTML5 semantic sections through an extension to Markdown, but that is obviously not part of CommonMark: https://blogs.pjjk.net/phil/html5-semantic-sections-with-markdown/

1 Like
10

I also find myself needing this to make my CSS work. I’m disappointed that the majority opinion seems to be that this is out of scope, but I don’t understand why you’d say it’s outright invalid. If I understand correctly, you’re saying that the HTML output must match CommonMark exactly in all configurations, regardless of what such a deviation would enable. That is a truly odd position.