Section headings are styled unevenly (solution included)

[ArthurClemens]

Headings "Summary", "Callbacks" and "Functions" are styled differently than headings with other titles.
These other headings are displayed quite a bit larger. These include the heading "Types", and custom headings generated by the @doc group tag (see screenshots below).

This is caused by very specific CSS selectors that include the section name-as-identifiers for "Summary", "Callbacks" and "Functions":

:is(#summary, #callbacks, #functions)>h1.section-heading
:is(#summary, #callbacks, #functions)>h2.section-heading

The selectors exclude sections with other IDs.

Changes

The currently generated HTML contains class name details-list that is unused by CSS.
This class can be used instead of the specific ID selectors.

In general.css, change:

& h2,
& :is(#summary, #callbacks, #functions)>h1.section-heading {
  font-size: var(--h2-size);
  margin-top: 1.5em;
  margin-bottom: 0.5em;
}

& h3,
& :is(#summary, #callbacks, #functions)>h2.section-heading,
& #summary :is(.summary-callbacks, .summary-functions) h2 {
  font-size: var(--h3-size);
  margin-top: 1.5em;
  margin-bottom: 0.5em;
}

to:

& h2,
.details-list h1 {
  font-size: var(--h2-size);
  margin-top: 1.5em;
  margin-bottom: 0.5em;
}

& h3,
.details-list h2 {
  font-size: var(--h3-size);
  margin-top: 1.5em;
  margin-bottom: 0.5em;
}

Screenshots current layout

Side-by-side comparison of a regular page and a page with heading "Types"

The Types heading inside Summary should be styled as h3 instead of h2.
The Types heading at the same level as Summary should be styled as h2 instead of h1.

Screenshots new layout

Side-by-side comparison of a regular page and a page with heading "Types"

The Types headings are aligned with the Function headings.

Side-by-side comparison of a page with headings for a custom group

Left the current styling, right the updated styling.
At the right side, the custom heading is aligned with the Summary heading.

[DavidOliver]

Thanks, @ArthurClemens - I'll try that out soon. It would be great if we could use that class as you describe.

[josevalim]

@DavidOliver then we would be able to reintroduce the minification, right?

[josevalim]

In any case, yeah, we should special case any of these headers, since we can have custom sections/groups. :)

[DavidOliver]

@DavidOliver then we would be able to reintroduce the minification, right?

Until esbuild reliably leaves :is() alone, we should probably leave minification off, unless we determine that :is() and other vulnerable aspects of CSS are not to be used in ExDoc at all, or otherwise work around the issue.

I should raise an issue at esbuild... :)

[ArthurClemens]

Without :is() you just have to write out the full selectors.

[DavidOliver]

It turns out simplifying selectors to that extent doesn't take into account other types of headings, such as the Modules and Mix Tasks headings on the API Reference page (also within .details-list class) and headings in docstring sections. I will likely attempt to improve and simplify the situation, probably changing the level of certain headings to match their page's context, at some point. For now, I'm merely adding the missing summary-type heading class to fix the one type of heading that is the wrong size.

Without :is() you just have to write out the full selectors.

Yes, though I'm not sure if we want to be in a position where contributors must not use what has become a basic function in CSS. Having said that, the :is() function was actually working okay everywhere I tested it despite the erroneous space inserted, so minification can be turned on again if @josevalim prefers.

[josevalim]

Yes, let's turn it back on :)