Learn front-end development with high quality, interactive courses from Scrimba. Enroll now!

MDN 2024 content updates title. A JavaScript logo, a pi mathematical symbol, an icon representing the web, and artwork of a smartphone.

MDN 2024 content projects

Author avatarVadim Makeev9 minute read

MDN Web Docs provides accurate and accessible resources for people getting started building for the web right through to professional developers. Our commitment includes maintenance of long-existing content and documenting features that are brand new to the web platform.

In 2024, the MDN content team chose some content areas to audit and update so they stay useful and relevant in an evolving web platform. We looked at topics that were popular but contained some outdated or incomplete material, and invested time in improvements, additions, and removing obsolete content.

This post recaps what we achieved in our content projects in 2024, highlights some of our top picks and recommended reading, and looks forward to what's next on MDN for 2025.

2024 MDN content areas

For 2024, we chose three technology categories that are popular, but had reader feedback that indicated they needed a refresh. We focused on HTTP, MathML, and web Manifests. From July to December 2024, the team worked through these areas to bring the quality up in a number of ways. Let's have a look at what changed in each section below.

MathML

MathML is an XML-based language for describing mathematical notation on the web. Similar to SVG, MathML can also be included in the HTML and rendered by the browser, no plugins or libraries are required.

n = 1 +
html
<math display="block">
  <munderover>
    <mo></mo>
    <mrow>
      <mi>n</mi>
      <mo>=</mo>
      <mn>1</mn>
    </mrow>
    <mrow>
      <mo>+</mo>
      <mn></mn>
    </mrow>
  </munderover>
</math>

Unlike the MathML Core specification, which often groups elements, MDN now features each MathML element on its page, with examples, usage notes, and BCD (browser-compat-data) now also updated. For example, you can read about <semantics>, <annotation> and <annotation-xml> elements and how they help to annotate MathML expressions.

Just like we're writing this blog post using Markdown instead of HTML, MathML is often generated by math processors using lightweight markup languages like LaTeX. To help content authors, all MathML examples now have annotations. For example, x2+yx^{2} + y can be written as x^{2} + y in LaTeX:

html
<math>
  <semantics>
    <mrow>
      <msup>
        <mi>x</mi>
        <mn>2</mn>
      </msup>
      <mo>+</mo>
      <mi>y</mi>
    </mrow>
    <!-- Annotated with LaTeX, a lightweight markup language. -->
    <annotation encoding="application/x-tex">x^{2} + y</annotation>
  </semantics>
</math>

This will also allow us to start using LaTeX for MathML in the future, making it easier for content authors to write and maintain examples. To fully appreciate the difference, you can compare the full MathML source code of some bigger examples, such as Deriving the Quadratic Formula and Proving the Pythagorean theorem, with their LaTeX equivalents.

MathML documentation on MDN now features accessibility information for all elements. For example, using <math> element for representing math content allows screen readers to read the formula, which makes MathML better for such cases than using images or other formats.

Additionally, all MathML features now have live examples, so you can see how they're rendered in your browser. And just like with other live examples on MDN, you can always click "Play" in the top right corner to play around with the code in a new tab.

Not only is MathML documented on MDN, but it's also used to describe different parts of the web platform. For example, Set.difference() JavaScript method, CSS transformation functions, 3D collision detection in game development, WebXR Device API, and many more.

We made sure MathML is now rendered correctly throughout MDN: inside paragraphs and on the block level, on big and small screens, and in different browsers.

Manifest (web app manifests)

A web app manifest is a JSON text file that provides information about a web application. The most common use for a manifest is to provide information that the browser needs to install a progressive web app (PWA) on a device, such as the app's name and icon.

json
{
  "name": "HackerWeb",
  "short_name": "HackerWeb",
  "start_url": "/index.html",
  "display": "standalone",
  "background_color": "#ffffff",
  "description": "A readable Hacker News app",
  "icons": [
    {
      "src": "images/icons/homescreen192.png",
      "sizes": "192x192",
      "type": "image/png"
    }
  ]
}

For the manifest content updates, Dipika collaborated with Firefox engineer Jonathan Almeida to update browser compatibility data for manifest members in Firefox. The manifest BCD additions now cover compat data for Firefox and Firefox for Android, ensuring accurate and up-to-date support information. Readers on MDN, Can I use, and other sites, now have solid guidance on manifest support across browsers.

On the content side, several improvements landed across the section for prose, layout and templating fixes. The page template is now improved for readability and consistency across the entire section. For each member value (for example, "display": "standalone",), there is a proper prose description, with example scenarios where the value might be used.

Usage notes are collected into a dedicated "Description" section, and any caveats that the specification mentioned that were not in the MDN pages and now documented. Some pages were missing "Syntax" sections completely, so now these gaps are filled so readers can better understand how to use the documented features and some possible member values:

json
/* Boolean values */
"prefer_related_applications": true
"prefer_related_applications": false

This refresh made sure that the existing content was more comprehensive and readable but also included references to similar features, which allowed for more flexibility for developers. For example, using prefers-color-scheme in HTML to set different theme_color values for light and dark mode:

html
<meta
  name="theme-color"
  content="#F4E6D8"
  media="(prefers-color-scheme: light)" />
<meta
  name="theme-color"
  content="#5D4037"
  media="(prefers-color-scheme: dark)" />

HTTP content updates

HTTP is a protocol that's foundational for data exchange on the web. It allows communication between browsers and servers, but it can also be used for machine-to-machine communication, automating access to APIs, and more. On MDN, the HTTP section has over 300 pages of reference material, and the majority of pages are about HTTP headers and response status codes.

Response status codes let the client know the outcome of a HTTP request (such as 200, 404), and give some additional context in certain cases. There are 61 status codes documented on MDN and they include examples for common responses and clarifications for rarer types that web developers may not encounter often. You can even make sure you're familiar with the 418 (I'm a teapot) status just in case.

There are 148 HTTP headers documented on MDN. HTTP headers are the parts of the HTTP message that carry metadata, information about the client or server, instructions for the recipient, and so on. Some headers have several sub-pages that describe mechanisms you can control via headers, such as Content Security Policy (CSP) directives that instruct a browser to restrict what the code comprising a site can run and Permissions Policy directives for requesting permission to use browser features such as location or microphone access.

The HTTP guides have overviews of how the protocol works, describing the evolution of the protocol from HTTP/0.9 right through to current versions. We document different ways to control HTTP interactions such as caching and conditional requests, and we have guides about how to use and understand the protocol for beginners, right up to more involved topics. A lot of the refresh of these guides meant making less specific references to HTTP/1.1 when talking about message formats seeing as HTTP/2 and HTTP/3 are increasingly common.

http
HEAD /en-US/docs/Web/HTTP HTTP/2
Host: developer.mozilla.org
User-Agent: curl/8.7.1
Accept: */*

* Request completely sent off
HTTP/2 200

To summarize, the changes we made across the entire HTTP section included adding examples where they were missing or too short to be useful, removing outdated or obsolete information, and making the formatting and presentation consistent over all pages.

HTTP highlights on MDN

Part of the refresh involved updating and adding sequence diagrams that explain client-server exchanges. We've been finding mermaid syntax useful for a lot of these types of diagrams as it makes it easier to store sources for images that we may need to update later.

These images are stored in the shared-assets repository, which allows us to reuse images instead of duplicate them in the source, and these are easier to write, read, maintain, and they look nice, too:

Like for a regular upload, the first upload of a resource is subject to a race condition: If-None-Match can prevent it.

One interesting pick from the HTTP section is the Server-Timing response header that you can use to surface server metrics to a client:

http
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 123
Date: Fri, 03 Jan 2025 10:41:21 GMT
Server-Timing: custom-metric;dur=123.45;desc="My custom metric"

--- response body ---

Depending on the type of request, you can decide if you want to send server timings to the client, and these are visible in the Network request details panel in most browser's developer tools. For example, the BBC iPlayer is using the Server-Timing header to send performance metrics about the service, visible in the Network > Timings panel below. If you find this interesting, be sure to check the Performance API and the Web performance documentation.

The 'Network > Timings' panel in Firefox developer tools.

For the HTTP section, most of the BCD updates involved improving the accuracy of existing entries and adding missing compat data for headers. Additions included the Service-Worker request header for logging service worker script requests and the Sec-Websocket-* headers used in the WebSocket handshake.

Most of the HTTP updates are for older features, but the accuracy of the support information is crucial for developers making decisions about what to build. One example is the Trailer compatibility details which now reflects browser implementations. It's important to avoid misleading information in compatibility tables because they may encourage people to develop functionality in their applications for features that have poor browser support in reality.

Other 2024 content highlights on MDN

Here's a few interesting picks of documentation that landed in 2024:

Aside from reference docs, we've written about these topics on the MDN blog:

We also blogged about these changes and launches:

Firefox release notes for developers

Firefox release notes describe what's changed for everyday browser users. The MDN team document each Firefox release with release notes specifically for developers. That means in 2024, Firefox versions 122 up to 133 have pages describing the changes in each Firefox release that developers can target. You can find everything in the Firefox release notes for developers pages.

Something you may not be aware of is that we also document Experimental features in Firefox. This page describes features implemented in Firefox that are only available behind a preference (though configuration). You can test out upcoming features before they are released, which is ideal if you're planning to use an experimental technology or if you're curious and would like to provide feedback on Bugzilla.

Kicking off 2025

The content projects that the team worked on were a superb learning experience, and we hope our readers benefit greatly from it. If you want to make our docs better, let us know if there are other sections that need attention, and even lend your expertise. If you want to learn about a topic, why not try to improve the documentation! By contributing to MDN, you can improve your skills in a technology category, and millions of readers will benefit from it.

We're happy to share that we saw the following contributions in mdn/content GitHub repository in 2024:

  • 915 different authors contributed.
  • ~4300 pull requests opened.
  • ~1500 issues opened.

We want to send out a big thanks to everyone who contributed in 2024 and we hope to see you continue in 2025. One of the first larger changes we're excited to see is that JavaScript Temporal is coming with support scheduled to land in Firefox 135. There is a huge pull request for Temporal authored by Josh-Cena, which means you can expect to be able to read Temporal documentation on MDN very soon.

We hope you enjoyed this post! Feel free to get in touch with us and let us know what you think.

Stay Informed with MDN

Get the MDN newsletter and never miss an update on the latest web development trends, tips, and best practices.