Welcome Yari: MDN Web Docs has a new platform

After several intense months of work on such a significant change, the day is finally upon us: MDN Web Docs’ new platform (codenamed Yari) is finally launched!

icon for yari, includes a man with a spear, plus the text yari, the mdn web docs platform

Between November 2 and December 14, we ran a beta period in which a number of our fabulous community members tested out the new platform, submitted content changes, allowed us to try out the new contribution workflow, and suggested improvements to both the platform and styling. All of you have our heartfelt thanks.

This post serves to provide an update on where we are now, what we’re aiming to do next, and what you can do to help.

Where we are now

We’ve pulled together a working system in a short amount of time that vastly improves on the previous platform, and solves a number of tangible issues. There is certainly a lot of work still to do, but this new release provides a stable base to iterate from, and you’ll see a lot of further improvements in the coming months. Here’s a peek at where we are now:

Contributing in GitHub

The most significant difference with the new platform is that we’ve decentralized the content from a SQL database to files in a git repository. To edit content, you now submit pull requests against the https://github.com/mdn/content repo, rather than editing the wiki using the old WYSIWYG editor.

This has a huge advantage in terms of contribution workflow — because it’s a GitHub repo, you can insert it into your workflow however you feel comfortable, mass changes are easier to make programmatically, and you can lump together edits across multiple pages in a single pull request rather than as scattered individual edits, and we can apply intelligent automatic linting to edits to speed up work.

The content repo initially comes with a few basic CLI tools to help you with fundamental tasks, such as yarn start (to create a live preview of what your document will look like when rendered on MDN), yarn content create (to add a new page), yarn content move (to move an existing page), etc. You can find more details of these, and other contribution instructions, in the repo’s README file.

Caring for the community

Community interactions will not just be improved, but transformed. You can now have a conversation about a change over a pull request before it is finalized and submitted, making suggestions and iterating, rather than worrying about getting it perfect the first time round.

We think that this model will give contributors more confidence in making changes, and allow us to build a much better relationship with our community and help them improve their contributions.

Reducing developer burden

Our developer maintenance burden is also now much reduced with this update. The existing (Kuma) platform is complex,  hard to maintain, and adding new features is very difficult. The update will vastly simplify the platform code — we estimate that we can remove a significant chunk of the existing codebase, meaning easier maintenance and contributions.

This is also true of our front-end architecture: The existing MDN platform has a number of front-end inconsistencies and accessibility issues, which we’ve wanted to tackle for some time. The move to a new, simplified platform gives us a perfect opportunity to fix such issues.

What we’re doing next

There are a number of things that we could do to further improve the new platform going forward. Last week, for example, we already talked about our plans for the future of l10n on MDN.

The first thing we’ll be working on in the new year is ironing out the kinks in the new platform. After that, we can start to serve our readers and contributors much better than before, implementing new features faster and more confidently, which will lead to an even more useful MDN, with an even more powerful contribution model.

The sections below are by no means definite, but they do provide a useful idea of what we’ve got planned next for the platform. We are aiming to publish a public roadmap in the future, so that you can find out where we’re at, and make suggestions.

Moving to Markdown

At its launch, the content is stored in HTML format. This is OK — we all know a little HTML — but it is not the most convenient format to edit and write, especially if you are creating a sizable new page from scratch. Most people find Markdown easier to write than HTML, so we want to eventually move to storing our core content in Markdown (or maybe some other format) rather than HTML.

Improving search

For a long time, the search functionality has been substandard on MDN. Going forward, we not only want to upgrade our search to return useful results, but we also want to search more usefully, for example fuzzy search, search by popularity search by titles, summaries, full text search, and more.

Representing MDN meta pages

Currently only the MDN content pages are represented in our new content repo. We’d eventually like to stop using our old home, profile, and search pages, which are still currently served from our old Django-based platform, and bring those into the new platform with all the advantages that it brings.

And there’s more!

We’d also like to start exploring:

  • Optimizing file attachments
  • Implementing and enforcing CSP on MDN
  • Automated linting and formatting of all code snippets
  • Gradually removing the old-style KumaScript macros that remain in MDN content, removing, rendering, or replacing them as appropriate. For example, link macros can just be rendered out, as standard HTML links will work fine, whereas all the sidebar macros we have should be replaced by a proper sidebar system built into the actual platform.

What you can do to help

As you’ll have seen from the above next steps, there is still a lot to do, and 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.

About Chris Mills

Chris Mills is a senior tech writer at Mozilla, where he writes docs and demos about open web apps, HTML/CSS/JavaScript, A11y, WebAssembly, and more. He loves tinkering around with web technologies, and gives occasional tech talks at conferences and universities. He used to work for Opera and W3C, and enjoys playing heavy metal drums and drinking good beer. He lives near Manchester, UK, with his good lady and three beautiful children.

More articles by Chris Mills…


10 comments

  1. maxloh

    The following MDN article suggest users to determine license of code samples by checking the time when they was added to MDN. If a code sample was added after August 20, 2010, it is CC0, otherwise it is MIT.
    https://developer.mozilla.org/en-US/docs/MDN/About#Copyrights_and_licenses

    However, this method doesn’t work anymore after MDN’s transition to Yari because the GitHub repo doesn’t contain articles’ history before 15 Sep 2020.

    How should we figure out which license applies to a specific code sample, after the transition to Yari?

    December 14th, 2020 at 17:37

    1. Chris Mills

      This is an issue, yes, and we’re currently looking into the best way to handle this. More soon.

      December 15th, 2020 at 00:27

  2. Al

    Congratulations!

    December 15th, 2020 at 04:44

  3. Yinsi Rio

    Off topic, but is the picture based on Yukimura Sanada from Samurai Warriors?

    December 15th, 2020 at 08:04

  4. Rami Yushuvaev

    Great news!

    @Chris , Is it final we can start using Markdown?

    December 15th, 2020 at 12:56

    1. Chris Mills

      Not yet ;-)

      Moving to markdown is in the roadmap for a future iteration of the platform.

      December 16th, 2020 at 01:28

  5. h.rayflood

    the samurai in logo picture is SANADA Yukimura from Samurai Warriors 4 created by KOEI TECMO HOLDINGS.
    https://www.gamecity.ne.jp/sengoku4/chara00.html
    https://www.koeitecmoamerica.com/sw4/chara00.html
    does this picture have any issues about copyright ? because this picture based on original image.

    December 15th, 2020 at 14:43

  6. Tim E

    This is very exciting! We’ve done a lot of research at Condé Nast about markdown, and I would say that it has lots of issues for non-technical contributors. If all folks using the docs are proficient in markdown, great!

    The issues we came up with are that all the markup data is in a “data lake” of sorts that makes it hard to bulk analyze or extract information from. This has made it hard for us to understand what features are used often and new features we should provide for editors.

    There’s no such thing as invalid markdown! This was something that caught me by surprise. To provide feedback, we need to understand what looks like a mistake.

    The rest of this is related to rich text editing, but it stands that these provided a major pain point for moving our editors from editing in markdown directly to rich text editing. Delimiter runs are complicated and understanding what the proper nesting for something without breaking what users intend is messy. Machine written markdown for 90% of things that are written is quite easy, but the rest of it becomes really difficult to do correctly. (I have personally spent several years working on code to wrangle our markdown).

    Finally, writing in markdown in languages that do not use spaces liberally makes it impossible to format specific ranges of text how they would like to (in part due to our custom markdown extensions). The reason for this in particular is due to how delimiter runs work in markdown and how they interact with spaces.

    (Also to note that markdown wasn’t intended for storage, see: https://twitter.com/gruber/status/1106278808137666563)

    If anyone would like to chat more, we’d be happy! Reach out, and congrats again on this milestone!

    December 15th, 2020 at 17:18

  7. Knissing

    it is great. can’t wait for contributing

    December 16th, 2020 at 19:58

  8. Sudarshan

    This is great news! Thanks for all your hard work.
    Will help to my greatest extent.

    December 26th, 2020 at 17:05

Comments are closed for this article.