Description
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.