OWD project: convert MDN content to Markdown

[wbamberg]

This proposes that we work on migrating MDN to use (GitHub-Flavored) Markdown instead of raw HTML for the authoring format.

Note that this is a joint project with the Mozilla MDN engineering team. We will need to work out how to divide responsibilities between OWD and MDN engineering so we can work together well. Note also that Mozilla are very likely to do this project anyway, with or without OWD involvement. However, OWD have a lot of:

• knowledge of MDN content and the problems it might pose for a Markdown conversion
• experience thinking through these problems
• opinions about the direction MDN's authoring format should take.

Problem statement

Before Yari, MDN docs were edited in a WYSIWYG editor, with an option to edit the page as raw HTML.

Since Yari, it's only possible to edit MDN docs as raw HTML in a text editor.

This is slower, more difficult and results in more formatting errors. It also results in worse documentation because authors have to think about the formatting all the time instead of the concepts they want to express. People who aren't familiar with HTML may not be able to contribute at all.

It's also harder to review.

Priority assessment

This table checks this project against the OWD prioritization criteria.

Criteria	Assessment
Effort	Large. We'd need to design all the tooling to convert from HTML to Markdown (for migration) and back into HTML (for rendering web pages). We'd need to convert a substantial section of MDN, and fix any problems.
Dependencies	Joint project with the MDN engineering team. OWD's specific contribution would be concerned with the authoring format, any customizations to basic Markdown that are needed to represent MDN pages, and ensuring that as far as possible we're enabling future work to structure MDN content.
Community enablement	Editing and reviewing Markdown is a lot easier than editing and reviewing HTML.
Momentum	N/A
Enabling learners	N/A
Enabling professionals	N/A
Underrepresented topics / ethical web	N/A
Operational necessities	Yes. Maintaining MDN content as HTML is not sustainable.
Addressing needs of the Web industry	N/A

Proposed solutions

In this project we would migrate a single subset of MDN docs to Markdown.
It would make sense for this to be a coherent part of the site, big enough to
discover the problems we're most likely to encounter, but small enough to be manageable. For example:

• all the JS docs: about 1000 pages, or 1/10 of all the en-US Web docs
• all the CSS docs: about 1000 pages, and probably more challenging than the JS docs

Then at the end of this project we would have:

• content for that section in Markdown in mdn/content
• documentation for authors, focusing especially on any customizations we have implemented
• extra tooling in Yari to convert this content into HTML

After this project we would convert the rest of MDN, section by section.

Task list

1. Analyze features of MDN content that are likely to make a straight Markdown conversion problematic, and design custom solutions to them. Solutions could include things like:
   • extending basic Markdown syntax to support them
   • writing new KumaScript macros so we can make them build parts of the page
   • documenting exceptions where authors must use raw HTML
2. Implement HTML->Markdown conversion that includes these customizations
3. Where content changes are needed, update the content
4. Implement Markdown->HTML conversion in Yari that reverses these customizations
5. Verify the rendered pages, and implement any extra customizations as needed.

[estelle]

w00t!