Including CSS “short descriptions” in mdn/data
The “short description” is the opening sentence or two of a CSS property reference page. It gives a very short overview of the property.
It follows a reasonably consistent pattern:
For example:
The
box-shadowCSS property is used to add shadow effects around an element’s frame. You can specify multiple effects separated by commas if you wish to do so. A box shadow is described by X and Y offsets relative to the element, blur and spread radii, and color.
The
marginCSS property sets the margin area on all four sides of an element. It is a shorthand for setting all individual margins at once:margin-top,margin-right,margin-bottom, andmargin-left.
Currently the short description is just part of the Wiki document for the property. It’s been proposed (e.g. https://github.com/mdn/data/issues/199) to move the short description out of the Wiki and into the JSON data structures in the mdn/data GitHub repository.
The rationale for doing this is that it makes it much easier for external tools to embed the short description. For example, an editor like VSCode could fetch the short description and display it in a contextual popup along with other useful information like browser compatibility. External tools can (and do) do this already by scraping the Wiki, but this is quite unreliable.
This document considers how we might go about moving the short description into an “externally embeddable” format such as mdn/data, and what the issues with doing this might be.
Precendents
This isn’t the first piece of MDN content to be moved out of the Wiki into an “externally embeddable” format.
-
The browser-compat-data project moves compatibility data from the Wiki into JSON files in GitHub, where it’s packaged into an npm module and can be consumed by external applications.
-
The existing contents of mdn/data
was originally content in the Wiki, that’s now accessible to external applications via a similar JSON=>npm setup.
One important difference is that this is the first time we’ve seriously considered migrating pure prose content out of the Wiki in this way, and this will bring its own challenges.
However, both the previous migrations listed above include some prose content:
-
browser compat includes “notes”, which are free text
-
the CSS data in mdn/data includes prose describing which elements the properties can apply to.
We’ll refer to both of these as possible precedents in meeting the challenges of migrating the short description.
The basic proposal
Adding the description to mdn/data
The mdn/data repository describes CSS properties in a properties.json file. Each entry contains data about a single CSS property, including its specification status and formal syntax. Here’s the entry for box-shadow:
"box-shadow": {
"syntax": "none | <shadow>#",
"media": "visual",
"inherited": false,
"animationType": "shadowList",
"percentages": "no",
"groups": [
"CSS Backgrounds and Borders"
],
"initial": "none",
"appliesto": "allElements",
"computed": "absoluteLengthsSpecifiedColorAsSpecified",
"order": "uniqueOrder",
"alsoAppliesTo": [
"::first-letter"
],
"status": "standard"
}
This data is currently used both in MDN pages and in external tools such as css-tree.
The obvious suggestion is to add the short description into this JSON structure:
"box-shadow": {
"syntax": "none | <shadow>#",
"media": "visual",
"inherited": false,
"animationType": "shadowList",
"percentages": "no",
"groups": [
"CSS Backgrounds and Borders"
],
"initial": "none",
"appliesto": "allElements",
"computed": "absoluteLengthsSpecifiedColorAsSpecified",
"order": "uniqueOrder",
"alsoAppliesTo": [
"::first-letter"
],
"status": "standard",
"shortDescription": "The box-shadow CSS property is used to add shadow effects around an element's frame. You can specify multiple effects separated by commas if you wish to do so. A box shadow is described by X and Y offsets relative to the element, blur and spread radii, and color."
}
Embedding short descriptions in MDN
Once we’ve done that, we’d want to be able to include the descriptions in MDN Wiki pages. The obvious approach would be to use a KumaScript macro to fetch the short description from mdn/data and embed it in the page. This is the same approach used to embed compatibility tables populated from browser-compat-data and to embed “info” tables populated from mdn/data.
Challenges and questions
Format
The first question: which format should we use for the short description? We’ll consider three options:
- HTML
- Markdown
- reStructuredText
The advantages of HTML are that it’s very powerful, well-specified, and tools to process it are readily available. The disadvantages are that it’s hard to write and hard to read. If we did choose HTML, we should greatly restrict the elements we permit.
The advantages of Markdown are that it’s very familiar, easy to write and easy to read. The disadvantages are that it’s not well-standardised, is very limited, and doesn’t support semantic markup.
reStructuredText is somewhere in between the other two options. It is simpler to read and write than HTML, but is better standardised, more powerful, and more extensible than Markdown, and supports semantic markup.
Recommendation
One hidden question here is: are we choosing a markup format for short descriptions only, or are we building the first step of a system to move more complex content out of the Wiki? We would like to choose the simplest format possible, but there’s a risk that it will prove inadequate if we start trying to do more with it. A related question is: how difficult would it be to change the markup format, if we discover that our choice is inadequate?
I think that at this point it’s difficult to anticipate what our future requirements will be or how we will want to address them, so we should do something simple for now and acknowledge that we might change formats later.
For notes in browser-compat-data, we use HTML, restricted to <a> and <code> elements, and it has worked quite well.
Looking through some short descriptions, I think this would be enough for short descriptions, with the possible addition of <strong>. If in the future we want to represent more complex content, such as descriptions of property syntax, we might have to consider different options, and I’d tend to favour reStructuredText.
Localization
MDN’s Wiki content is provided in a number of languages. It’s translated entirely by volunteers, and provides its own platform for translators. The platform has serious limitations but it is possible for determined volunteers to create and maintain high-quality translations.
If we move the en-US text out of the Wiki and include it using a macro, how will localization be affected?
The two precedents we have for this project take different approaches here.
browser-compat-data
In the browser-compat-data project, we don’t (yet) address localization at all. Notes are given in en-US only, and are presented in en-US in all locales. This is probably more acceptable for notes in a table than for the first paragraph of the article, though!
Note that even if we don’t support localization explicitly in this project, it’s still possible for people to provide translations for the short description. The en-US page would include the {{ShortDescription}} macro. Translators could use the rendered version of the en-US page as the source, and other locales would include the translated text content directly, rather than the macro call.
But this means translators get no help from the localization tools in Kuma, and have to treat short descriptions as a special case.
mdn/data
In mdn/data, we do address localization explicitly. Localizable strings are referred to using identifiers, which can be used as keys to look up strings in a separate l10n dictionary:
// css/properties.json
"box-shadow": {
...
"computed": "absoluteLengthsSpecifiedColorAsSpecified",
...
}
// l10n/css.json
"absoluteLengthsSpecifiedColorAsSpecified": {
"de": "Längen absolut gemacht; angegebene Farben berechnet; ansonsten wie angegeben",
"en-US": "any length made absolute; any specified color computed; otherwise as specified",
"fr": "toute longueur sous forme absolue; toute couleur sous forme calculée; sinon comme spécifié",
"ja": "指定値（length は全て絶対値となり、color については計算値となる）",
"ru": "любая абсолютная длина; работает любой указанный цвет; если другое не указано"
}
This system is used by the cssinfo macro.
Recommendation
We need some kind of localization answer for short descriptions, even in the first version. I don’t think it’s acceptable to do the same as browser-compat-data here - this is just because notes in a table are so much less obvious than the first paragraph of an article.
I’d recommend that we do the same thing as the other mdn/data items, as described above. But I’d really value input from localization experts and practitioners here.
As an aside: our localization strategy as a whole is unclear at the moment, and hopefully changes are going to come in this area.
Inline macros
The MDN Wiki platform, also known as Kuma, has its own macro system called KumaScript. It’s used for a wide variety of purposes, from macros like {{compat}} that build complete sections of the page, to what we could call “inline macros” that insert small bits of generated content inside static content. A major category of inline macros are cross-referencing macros, that generate links to documents.
Calls to inline KumaScript macros sometimes appear in the short description. For example, the short description for margin calls the {{cssxref}} macro, which generates a link to a page in the MDN CSS reference documentation:
The margin CSS property sets the margin area on all four sides of an element. It is a shorthand for setting all individual margins at once: {{cssxref(“margin-top”)}}, {{cssxref(“margin-right”)}}, {{cssxref(“margin-bottom”)}}, and {{cssxref(“margin-left”)}}.
This is a problem for opening up Wiki content to other applications, because these macros are not usable by applications other than Kuma. For example, suppose VSCode wants to fetch a short description for margin and gets the content quoted above. What can it do with {{cssxref("margin-right")}}?
So: when the short description’s content is moved out of the Wiki for consumption by other applications, what should happen to the macros it contains?
Recommendation
My recommendation here is that we deprecate these inline macros and remove them from the short description’s content.
The most common macro appearing in short descriptions is {{cssxref}}, and we can replace this with just standard HTML <a> and <code> elements.
Note though that this will apply to all content that we want to make available to applications that aren’t Kuma, so if we want to extend the scope of this project beyond just short descriptions, its impact on KumaScript macros will be more widespread.
In this context it would be helpful for the MDN team to have guidelines about the proper scope and valid applications for KumaScript macros.
Editing workflow
Moving content out of the Wiki into GitHub is a big change to the contribution workflow. We’ve seen with browser-compat-data and interactive-examples that we still get good contributions from GitHub-hosted content, but prose content feels different from either structured data or code examples.
I’m not sure what to suggest here, other than to try it and see if it is successful.
The future
One major open question is: how does this change fit into our overall platform strategy for MDN? We are considering migrating more content out of the Wiki and into GitHub. It’s always tempting to make moves like this incrementally, testing each step before moving on. This has been our approach so far with experiments like browser-compat-data, mdn/data, and interactive-examples.
But the risk of this incremental approach is that by proceeding without an overall vision, you end up with an incoherent mess. How can we have confidence that the “short descriptions” project will fit cleanly into a “future MDN” where, for example, all reference content is externally embeddable? Would it be better to have even a sketched out vision of our endpoint, to guide the incremental steps we take?
