wbamberg

There are three pieces we need to think about in migrating MDN to Markdown:

1. how we should represent MDN content using Markdown
2. how we should convert MDN's HTML content into that Markdown representation
3. updating/adapting Yari tooling to work with Markdown as the authoring format

Representing MDN in Markdown

For this we need to think of the places in MDN where we're currently using features of HTML that can't be represented in our chosen Markdown (GFM, very likely). For each of these features, we can choose between about four options:

wbamberg

This file is just a list of the textContent of all first paragraphs of pages in the JS docs that **do not** use `summary` or `seoSummary` to demarcate a custom summary.
The point is to give us an idea of the general length of summaries that are being generated for the JS docs.

*********************

Why a re-introduction? Because JavaScript is notorious for being misunderstood. It is often derided as being a toy, but beneath its layer of deceptive simplicity, powerful language features await. JavaScript is now used by an incredible number of high-profile applications, showing that deeper knowledge of this technology is an important skill for any web or mobile developer.

*********************

JavaScript® (often shortened to JS) is a lightweight, interpreted, object-oriented language with first-class functions, and is best known as the scripting language for Web pages, but it's used in many non-browser environments as well. It is a prototype-based, multi-paradigm scripting language that is dynamic, and suppo

wbamberg

"use strict";

const fs = require("fs")
const path = require("path")

const jsdom = require("jsdom");
const { JSDOM } = jsdom;

/* get all ".html" files under the given directory into an array */
function getAllFiles(dirPath, files) {

wbamberg

Changelog

This is version 1.2.2 of the Matrix specification.

Versions for the Matrix specification follow a three-part format like major.minor.patch.

• major version increments are reserved for very significant changes.
• minor version increments may signal additions, deprecations, or breaking changes.
• patch versions are for clarifications to the specification and don't affect implementations.

wbamberg

In matrix-doc:

/                                      <- overview
    /client-server                     <- client-server
    /server-server                     <- etc
    /rooms
        /v1                            <- room version 1
        /v2                            <- etc

matrix-doc could also contain:

wbamberg

  125:1-125:32  error    data.examples not expected in this order                   javascript-language-feature/ingredient-out-of-order/data.examples               html-require-ingredient-order
  229:1-229:44  error    data.specifications not expected in this order             javascript-language-feature/ingredient-out-of-order/data.specifications         html-require-ingredient-order
  244:1-244:58  error    data.browser_compatibility not expected in this order      javascript-language-feature/ingredient-out-of-order/data.browser_compatibility  html-require-ingredient-order
  250:1-250:54  error    prose.* (#Cross-browser_notes) not expected in this order  javascript-language-feature/ingredient-out-of-order/prose.*                     html-require-ingredient-order

wbamberg

    // get all the ingredients from the recipe that were present in the page, plus "prose.*"
    const filteredRecipeIngredients = file.data.recipe.body.filter(
      (ingredient) =>
        pageIngredientNames.includes(ingredient) || ingredient === "prose.*"
    );
    // get the index of the "prose.*" ingredient in the recipe
    const indexOfProseStar = filteredRecipeIngredients.indexOf("prose.*");
    if (indexOfProseStar !== -1) {
      // get the ingredients before and after prose.* in the recipe

wbamberg

JavaScript reference docs structure specification

This document describes the structure we want to require for JavaScript reference documentation.

Recipes and ingredients overview

It is expected that pages documenting different sorts of thing will need to contain different elements. For example, the page for the JavaScript BigInt class will want to contain lists of links to its members, while the page for the JavaScript BigInt.asUintN() static method will want to contain a section describing the method syntax.

To reflect this, a "recipe" is a short YAML file that describes at a high level the elements that a particular type of page is expected to have. A recipe provides a list of elements, that are expected to appear in the page in the order given. So for each distinct type of page, we define a single recipe.

wbamberg

"use strict";

function toBinary(string) {
  const codeUnits = new Uint16Array(string.length);
  for (let i = 0; i < codeUnits.length; i++) {
    codeUnits[i] = string.charCodeAt(i);
  }
  return String.fromCharCode(...new Uint8Array(codeUnits.buffer));
}

wbamberg

<div class="bc-data" id="bcd:html.elements.video"><a class="bc-github-link external" href="https://github.com/mdn/browser-compat-data" rel="noopener">Update compatibility data on GitHub</a><table class="bc-table bc-table-web"><thead><tr class="bc-platforms"><td></td><th class="bc-platform-desktop" colspan="6"><span>Desktop</span></th><th class="bc-platform-mobile" colspan="6"><span>Mobile</span></th></tr><tr class="bc-browsers"><td></td><th class="bc-browser-chrome"><span class="bc-head-txt-label bc-head-icon-chrome">Chrome</span></th><th class="bc-browser-edge"><span class="bc-head-txt-label bc-head-icon-edge">Edge</span></th><th class="bc-browser-firefox"><span class="bc-head-txt-label bc-head-icon-firefox">Firefox</span></th><th class="bc-browser-ie"><span class="bc-head-txt-label bc-head-icon-ie">Internet Explorer</span></th><th class="bc-browser-opera"><span class="bc-head-txt-label bc-head-icon-opera">Opera</span></th><th class="bc-browser-safari"><span class="bc-head-txt-label bc-head-icon-safari">Safa