ReadMe Flavored Markdown (#306 Rebase)

[rafegoldberg]

🎟 Asana	📋 ReadMe-Flavored Markdown Syntax

By default, the updated @readme/markdown package exports a function which takes a string of ReadMe-flavored markdown and returns a tree of React components:

import ReactDOM from 'react-dom';
import rdmd from "@readme/markdown";

const root = document.getElementById('root');
const text = `[Gist Embed](https://gist.github.com/rezvitsky/de98114c1998de569d3cf40cef544b24 "@github")`;

ReactDom.render('div', { className: 'markdown-body', rdmd.react(text))

In addition to the default React processor, the package exports a few other methods for transforming ReadMe-flavored markdown:

import * as rdmd from "@readme/markdown";

...which will give you:

rdmd[key]	Description	Arguments
html	transform markdown in to HTML	text, options
ast	transform markdown to an mdast object	text, options
md	transform mdast in to ReadMe-flavored markdown	tree, options
utils	default options; various utility methods	N/A

[rafegoldberg]

sorting out the last kinks before this gets merged in:

• initial three-column layout support
• extending code coverage
• sanitizing raw html
  (pretty sure this should "just work", but I know there are some potential security issues here so this could probably use 👀s)
• updating various consumer implementations
  (I've updated the ones in the api-explorer sub-package itself, and in the main ReadMe app as well.)
• how we render embedded content
  (I haven't given this enough thought outside of the context of the new editor, so we should probably give this a bit of consideration.)
• variable/glossary context providers
  (they're there; they work! but it could use going over...)
• TOC generation
  (auto-generate left-hand TOC list and hash anchors for Guides Pages)
• baseUrl link expansion

[erunion]

@rafegoldberg When this is good to go, would you like to split it out of the explorer repo?

[rafegoldberg]

@erunion I don’t know if splitting it out is necessary, unless you think so? In any case, this should be ready to go anytime in Jan., once we’ve gotten support to QA and have their go-ahead.

[rafegoldberg]

(/also when I figure out how to get the tests working up to e’eryones satisfaction.)

[erunion]

@rafegoldberg yeah was just thinking aloud and wondering if it made sense to continue to bundle the markdown work alongside the explorer.

[domharrington]

I'm happy keeping Markdown as part of this repo for now, since we wouldnt get much benefit splitting it out apart from causing lots of npm link issues in development. Maybe the top-level name api-explorer makes less sense going forward?

[erunion]

Changed the base of this off master and onto a new release/v5 branch we can use when tagging 5.0 release candidates.

[erunion]

sorry

[erunion]

Unrelated to this PR, but we should probably swap this out with @readme/emojis.

[erunion]

lgtm! feel free to merge after pulling the latest release/v5 in here.