OWD project: Provide an embeddable version of HTML and CSS reference documentation

[wbamberg]

Problem statement

Developer tools often integrate reference documentation about web platform technologies. For example, Chrome DevTools and VS Code both display popups that contain information about CSS properties.

These tools need an embeddable way to represent this documentation, so they can display it in the correct context. Typically these tools maintain their own copy of this documentation-data, sometimes partially integrating it from other sources like browser-compat-data or mdn/content. This is an ongoing maintenance burden for these projects, and the documentation-data is often not up to date. Because the maintainers of these tools are not always familiar with the content or organization of the source material it is hard for them to update it or to know what additional useful data might be available.

Proposed solutions

The proposal is that Open Web Docs create and regularly update one or more npm packages containing structured documentation for HTML and CSS. This includes:

• HTML elements
• CSS properties, at-rules, selectors, functions, keywords, types

The content could be drawn from various sources:

• MDN's mdn/browser-compat-data repo, for structured browser compatibility data
• MDN's mdn/content repo, for prose content and examples
• W3C's webref package, for content extracted from the specifications

The structured documentation would be made available as JSON, and would enable a caller to use an identifier like css.properties.margin or css.types.color as a key to retrieve an object containing the documentation for that item.

Content

The data provided for an item is not completely defined and would depend on the type of item, but for CSS properties it could include:

• A short (one sentence) description of the item
• A link to the MDN page
• A link to specifications for the item
• BCD for the item
• A link to an interactive example (e.g. https://interactive-examples.mdn.mozilla.net/pages/css/margin.html)
• An example that illustrates the syntax
• Formal syntax, including constituent syntaxes
• For shorthand properties, a list of the constituent properties
• A prose description of potential accessibility issues with the item

Composability

Rather than deliver a single package, we might deliver multiple packages, so consumers can choose which data they want to include. So if a consumer wants only CSS descriptions, but no BCD or spec info, they don’t have to include the parts they don’t need.

Questions

Why CSS and HTML?

We think it will be possible to do something similar to this for all the main parts of the MDN reference documentation: JavaScript, CSS, Web/APIs, HTML, HTTP. We've chosen CSS and HTML first because:

• they're big enough to be a good test of how well it will work
• they're fairly well structured now, so we have a good understanding of what we could get out of them
• there are already clients who could make immediate use of them.

Will content be localized?

If there's enough demand.

What will the license be?

CC-BY-SA: this is the license that MDN uses for content.

What format will be used for prose?

A very restricted set of HTML: essentially, the same set of HTML that MDN’s Markdown is capable of expressing.

There are a few HTML elements that are included “raw” in the source, like <kbd>..

Task list

• Decide on a high-level organization for CSS
• Decide on a high-level organization for HTML
• Implement MDN Markdown to HTML conversion
• Implement KumaScript macro rendering
• Implement query layer over webref/css
• ...

Priority assessment

No response

More information

Open Web Docs (OWD) is a non-profit collective funded by corporate and individual donations.

In order for this project to happen, please consider donating to OWD on https://opencollective.com/open-web-docs.
For more information on sponsorship and membership tiers, see https://openwebdocs.org/membership/

More information is available at https://openwebdocs.org/.
For questions, please reach out to florian@openwebdocs.org.

[wbamberg]

One thing that's come up is how to handle internal MDN links. These links are usually going to be relative, like /en-US/docs/Web/SVG/Attribute/end, but might be absolute. They are often going to be generated by xref macros, but might be literal links in the source.

From the embedder's point of view: if a link appears in the embedded content it needs to go somewhere. But embedders might have quite application-specific requirements about what should happen with links. They might:

• want links to go to MDN pages
• want to remove links entirely
• want links to go somewhere else

Also, they might want different policies for different targets (so for example, they might want links to CSS property pages to go somewhere else, but all other links to go to MDN pages).

I think the best policy is:

• at the xref-rendering stage, have xrefs produce absolute MDN links, like https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/end
• at the JSON-building stage, guarantee that all links included will be absolute MDN links

Then the embedder can decide if it wants to rewrite any links, but if they do nothing, links will still at least work.

[yarusome]

Two questions:

1. Will these refs have localized versions?

   Popular IDEs like VS Code definitely need localized refs, and it seems inconsistent to only have the en-US version maintained while leaving l10n maintenance to each IDE's team.

2. What's the interaction between this project with mdn/data?

   The goal of this project and that of mdn/data seems quite overlapped: to provide concise, clear (e.g. among multiple levels of a CSS module) and up-to-date refs along with l10n. (Although conciseness is not explicitly mentioned in mdn/data's goal, it effectively is there.)

[wbamberg]

Two questions:

1. Will these refs have localized versions?
   Popular IDEs like VS Code definitely need localized refs, and it seems inconsistent to only have the en-US version maintained while leaving l10n maintenance to each IDE's team.

This is mentioned up there^. If consumers want localized versions we will try to provide them. I think the answer is a bit nuanced though.

• For MDN content and for locales supported by MDN, of course that's possible.
• Then a lot of content is not localizable (CSS formal syntax, for example, or the list of properties that are set by a shorthand).
• For other content, I'm not sure. For instance, if we wanted to include prose content from the specs, we'd have to have our own localization for that, and I'm not anticipating doing that yet. Similarly for prose content in BCD.

2. What's the interaction between this project with mdn/data?
   The goal of this project and that of mdn/data seems quite overlapped: to provide concise, clear (e.g. among multiple levels of a CSS module) and up-to-date refs along with l10n. (Although conciseness is not explicitly mentioned in mdn/data's goal, it effectively is there.)

I think mdn/data is a kind of prototype for this. The main difference though is that the content is not maintained by this tool: instead this tool compiles data from other sources (MDN, webref, BCD).

Does that help clarify things at all?