Mozilla Developer Network (MDN), Mozilla’s multilingual resource for web documentation, recently launched Yari, MDN Web Docs’ new platform. Yari reduces the burden of developing, maintaining, and contributing to MDN. MDN content is now stored in GitHub and can be contributed to via pull requests.
Chris Mills explained in a blog post:
For quite some time now, the MDN developer team has been planning a radical platform change […]. In short, we are updating the platform to move the content from a MySQL database to being hosted in a GitHub repository.
The new JAMStack approach separates MDN readers (99% of MDN’s traffic) from MDN contributors. Pre-rendered MDN content can be better cached and accessed quicker. GitHub is used as a content management system (CMS), replacing a large body of code from the Wiki platform that thus no longer has to be maintained. The new platform is also more agile from Yari developers. The Yari team detailed:
We can, for example, perform automated linting and testing on each content pull request, which allows us to better control quality and security.
The contribution workflow has significant advantages:
We no longer have spam content live on the site, with us then having to revert the changes after the fact. You are also free to edit MDN content in whatever way suits you best — your favorite IDE or code editor — and you can add MDN documentation into your preferred toolchain (and write your own tools to edit your MDN editing experience).
[…]
We are also looking into a powerful toolset that will allow us to enhance the reviewing process, for example as part of a CI process — automatically detecting and closing spam PRs, and as mentioned earlier on, linting pages once they’ve been edited, and delivering feedback to editors. […] Having MDN in a GitHub repo also offers much easier mass edits; blanket content changes have previously been very difficult.
Contributors may face longer feedback time. The previous platform let contributors click Edit on a page, make and save a change, and have it show up nearly immediately on the page. Contributors can however use GitHub UI’s edit feature and submit a pull request (PR), another GitHub GUI tool (e.g., GitHub Desktop), or the git CLI tool. While the Yari team plans to switch to Markdown, contributors need to edit raw HTML to update a document.
MDN content is now stored in the https://github.com/mdn/content GitHub repository. Content is organized hierarchically, with documents being folders containing the actual document content in an index.html file. The document architecture mirrors the MDN site architecture. The content of the https://developer.mozilla.org/en-US/docs/Web/API/CSSAnimation MDN page is stored at https://github.com/mdn/content/blob/main/files/en-us/web/api/cssanimation/index.html. Content starts with a YAML header containing meta-information about the document followed by the actual content displayed to readers:
---
title: CSSAnimation
slug: Web/API/CSSAnimation
tags:
- API
- Animation
- CSSAnimation
- Interface
- Reference
Yari also offers more consistency and accessibility. MDN created a new design system, codenamed Fiori, and MDN-Minimalist, a small set of core atoms that power MDN base styling.
GitHub pull requests additionally allows giving visible feedback where previously contributors would make changes without knowing if they went through. GitHub PR may serve as discussion space around content modification proposals.
The previous MDN platform used React server-side rendering and a Kubernetes cluster to serve both MDN readers and contributors through a CDN with a 5mn cache period:
(Source: MDN blog post)
The new platform pre-renders MDN content that is deployed daily to Amazon S3. Readers are served pages via a CDN with a much longer cache period:
The previous React stack which replaced jQuery in a redesign dating from 2019 had been criticized by some developers. Some developers commented that given the role that Mozilla plays in the promotion of web standards, the new version of the site should leverage those rather than using a non-standard framework. Others remarked that the content, being mostly static, did not require a JavaScript framework.
The Yari team plans to move MDN content from HTML to Markdown, improve the search functionality, and improve the status of internationalization. Following Mozilla’s recent restructuring, which included its disinvestment from MDN, the new platform will be instrumental to the continued development of MDN by the community. Mills emphasized that community help is very welcome:
We’d love the community to help us with future MDN content and platform work.
- If you are more interested in helping with content work, you can find out how to help at Contributing to MDN
- If you are more interested in helping with MDN platform development, the best place to learn where to start is the Yari README
- In terms of finding a good general place to chat about MDN, you can join the discussion on the MDN Web Docs chat room on Matrix
MDN started as Netscape DevEdge documentation, became Mozilla Developer Center (MDC), and was only named Mozilla Developer Network in 2010.