Make `<section/>` wrappers optional (for HTML)

[Brixy]

Thank you so much for Djot. Djot will definitely end hopping between markdown and asciidoctor for me.

---

I, too, have been using Djot in production, and it’s a great experience.

From what I can tell the <section/> wrapper can cause some troubles—in HTML context.

In this post @jgm asks

As for ugliness, I think it's no more ugly that {section=false} (though perhaps less explicit as to its purpose, at least for people who know English).

What's the real-world case that is motivating this?

In all our webprojects we use these CSS rulesets:

* {
	margin: 0;
}

.flow > * + * {
	margin-top: 1.5em;
}

The flow class is added to <main> or some selected content wrappers.

The content within any automatically generated wrapper is not affected, of course.

Moreover <section/> is frequently used to group content ‘manually’ and visually, e.g. for zebra styles, alternating right-left/left-right aligned content etc.

All in all I think <section/> is rather a layout than a content tag (just like in this HTML minifier).

Possible solutions:

• Option to make <section/> wrappers optional
• Option to define a standard class name that is added to all Djot-generated <section/> tags (e.g. flow)

Thank you!

[jgm]

All in all I think

is rather a layout than a content tag (just like in this HTML minifier).

I think we're using <section> correctly, judging from the documentation here.

You can use a filter to remove the section entirely:

return {
  section: (el) => {
    return el.children;
  }
}

Save as nosection.js and run with djot --filter nosection.js.

This will also remove the automatic identifiers, though. Alternatively, you could add a special class:

return {
  section: (el) => {
    el.attributes.class = "djot";
  }
}

If you're using djot as a library, you could also use the HTML renderer override documented on the readme, to render the section as something else...

[matklad]

I think we're using

correctly, judging from the documentation here.

One difference is that the example here doesn't have the topmost section wrapping h1, which also the behavior I want (for my blog, I put djot's result into an <article>). But this really is just ambiguity between using # for sub-section titles and for the document title.

[Brixy]

Thank you, John, for your answer and technical insights. Very interesting and helpful.

I think we're using <section> correctly, judging from the documentation here.

Yes, of course: The generated HTML code is not only valid but also semantic.

Actually I forgot to mention one point: I was not talking about djot-to-HTML standalone files but about (rather complex) webprojects generated with an SSG using Djot as the markup language for the content. In these cases wrappers around the actual content may cause problems and break the design, depending on the project.

Of course, it is always possible to adress these problems with CSS (but it gets trickier), and it’s good to know how to turn Djot’s wrapping functionalities of if needed.

Thanks again—and thank you so much for Djot!

[Brixy]

One difference is that the example here doesn't have the topmost section wrapping h1 …

Good point. (It has always been a problem that HTML lacks some kind of title tag for the body. Using h1 was not the best idea and caused a lot confusion.)