This document provides a record of MDN content processes, constructs, and best practices that have changed, and when they changed. It is useful to allow regular contributors to check in and see what has changed about the process of creating content for MDN.
The MDN project documentation is refreshed and organized under two main categories:
- Writing: Documentation about how to write for MDN, what we document, definitions of experimental, style guidelines and so on are found under the Writing guidelines pages.
- Community: Information about open source etiquette, discussions, processes for pull requests and issues, users and teams, and general hints for contributors are found under the Community pages.
For more details on what has changed, see the Revamp of MDN Web Docs Contribution Docs blog post published to Mozilla Hacks.
Conversion to Markdown is done, so remove the old CSS style guide and redirect to the Markdown in MDN page.
Multiple updates to the CSS style guide to reflect the move towards Markdown, and encourage authors to write HTML in a Markdown-compatible way.
Note and warning boxes no longer have a separate
<h4>heading for the title (e.g.
<h4>Warning</h4>). See our Markdown in MDN guide for the correct syntax.
seoSummaryclass should no longer be used.
standard-tableclass should no longer be used. The styling provided by this class is now applied to tables by default.
<details>element should no longer be used.
example-badclasses used to be primarily for code blocks but could be used on other elements. Now they can only be used on code blocks.
This was problematic — many developers were confused by this, and it conflicts with valid syntax forms in other programming languages (e.g.
As a result, going forward we are now writing multiple syntax forms of a method on separate lines inside the syntax block. See Syntax sections > Multiple lines/Optional parameters for further information and examples.
Interface mixins in Web IDL are used in specifications to define Web APIs. For web developers, they aren't observable directly; they act as helpers to avoid repeating API definitions.
Previously we commonly defined a landing page for a mixin class itself, and put the defined members on subpages underneath it, before linking to those from the landing pages of the interfaces that implement those mixins. This was confusing for readers because mixins are spec constructs — you never access the defined members using the mixin classes. To avoid this confusion we've instead put the pages for members defined on mixins directly under the implementing class pages. For more details, see the guide page on how to write an API reference and the discussion leading to this change at mdn/content#1940.
Previously on MDN, note and warning boxes would be wrapped by
<div> elements with
warning classes, respectively. More often than not, their first paragraphs would start with a
In January this changed — the
class attribute should now include an additional
notecard class, and the strong text is instead included in a heading at the top of the block.
See our Markdown in MDN guide for further information and syntax guides.