Define content authoring format(s)

[ALRubinger]

We've been standardizing around Markdown as an authoring format. This is great for content contributors: clear, well-documented, lightweight format for writing content.

It also lets us add "flavors" like specific extensions we can render on the page beyond standard Markdown, for instance if we want to do something like "embed a terminal command", like this example from expo.dev:

We also potentially have more structured needs beyond what Markdown can provide. Consider also from expo.dev, this docs home:

This is implemented as a straight-up React page.

This kind of intentional layout is likely more than we can get with Markdown alone; it gives more control to us to get precise about how we'd like things surfaced on the page.

So:

• Is that greater control something we build into our Markdown support as a "flavor", leaving the content authoring format to a Markdown flavor we document?
• Are those pages instead done in something like React or MDX?
• If it does necessitate MDX/React, does that give us 2 potential authoring formats?
• ...and based on those decisions, we've got to document in our docs contribution guide.

Let's get a decision on this for Phase 2, even if that decision is "we'll only support Markdown as-is for this Phase, and iterate on structured content like the example above for Phase 3."

[dayhaysoos]

After talking to @bobbilee19 about this:

• There will be two authoring formats: MDX and React (we can still process MDX files even if the format ends in .md

MDX will be used for the docs content, such as Intros, Tutorials, getting started pages or anything that pertains to the actual learning content.

React pages will be used for initial "home pages" of docs sections. For example, /docs will be a page done in React.

We don't want our initial pages to have the look and feel of a regular docs page.