Skip to content

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

Open
@wbamberg

Description

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    needs fundingproposal (actionable)Enough information is provided and the work is scoped well. Actionable but not prioritized right now

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions