[Markdown] Decide what to do about class="summary" and class="seoSummary" #3923
Description
seoSummary and summary are classes that get applied to prose content in MDN pages. They're used to help calculate a thing we'll call a "page summary". The calculation is a bit complicated (https://github.com/mdn/yari/blob/main/kumascript/src/info.js#L202), but in general, it's something like:
- if
span.seoSummaryexists in the page, then its content is taken as the page summary - otherwise, if any
.summaryelement exists in the page, then its content is taken as the page summary - otherwise, the summary is taken from the first
pelement in the document that does not live in a note or warningdiv.
So essentially these classes are used to provide a custom page summary, and if they are not given we default to using the first paragraph.
What's the page summary used for?
It's used in (at least) a couple of ways:
-
as described in https://developer.mozilla.org/en-US/docs/MDN/Guidelines/CSS_style_guide#.seosummary (although the
.summarypart is not documented) it gets used as the value of a<meta>tag in the page<head>, to provide a description that is embedded in search engine results and other embedding contexts. -
it's available to KumaScript, and seems to be used in the following macros:
- InterfaceOverview
- Index
- HTMLRef
- GlossaryList
- GlossaryDisambiguation
- HTMLRefTable
- LearnBox
- SubpagesWithSummaries
- LandingPageListSubpages
How widely are summary and seoSummary used?
Across all en-US, I count:
- 1322 uses of the
summaryclass - 2285 uses of the
seoSummaryclass
Across just JavaScript:
- 24 uses of the
summaryclass - 105 uses of the
seoSummaryclass
How should we handle them in Markdown-land?
The most obvious option is: stop supporting them, and just always use the first non-note paragraph for the page summary. It would be good to know if we would be regressing many pages by doing this.
Many pages just mark up the first paragraph with summary or seoSummary, so removing those classes would have no actual impact. For example:
However, some actually do use it to override the default:
It would I think be worthwhile to:
- analyse how many of the thousands of uses of these classes are actually no-ops
- remove the no-ops
- make a plan for the remainder.
We should also do an analysis of how KS macros are using the page summary, and whether they would be broken by removing the ability to override the default.
If we did decide it's important to let pages override the "first paragraph rule", we could consider having an optional front matter key for this, and we might also consider whether this is the same as the "short description" that we've talked about before as a component of our pages.
For now, we could limit this exercise to the JavaScript docs.
( @escattone , we talked about this issue yesterday)