Mdx: 🎬 MDX landing page

[johno]

MDX landing page

It's prolly about time MDX got a landing page. Here's some rough thoughts on what I've been thinking about. Would love to hear other's thoughts as well.

This is intended to start a discussion on what type of content would go nicely and what the basic structure _could_ look like. We're interested in any and all thoughts.

Goals

The primary goal is to better describe MDX in a more accessible way. For less tech-savvy users it's a rough landing to visit mdxjs.com and end up directly in docs. We currently don't explain it well either (that's definitely on me).

It'd also be better to go more in depth on why MDX was created: to empower authors to write dynamic, engaging, and immersive content.

Terms

The following things I think might be good to emphasize (or something like it):

• Markdown for the component era
• Authorable format
• makes writing long-form content with components a blast 🚀

Sections

The following sections would be nice to have (maybe some are overkill or I'm missing better possible sections):

Playground

It might be better to show than tell so we could have a live editable MDX editor.

How it works

I think it'd be cool to show the three "stages". Ideally the HTML section will be actually rendered. Maybe this could even be dynamic?

1. MDX

import TomatoBox from 'tomato-box'

export author = "Fred Flintstone"
export default = props => <main {...props} />

# Hello, world!

Here is a paragraph

<TomatoBox />

1. JSX

import TomatoBox from 'tomato-box'

const MDXLayout = props => <main {...props} />

const layoutProps = {
  author: "Fred Flintstone"
}

export default function MDXContent(props) {
  return (
    <div name="wrapper" components={components}>
      <MDXLayout {...layoutProps} {...props}>
        <h1>{`Hello, world!`}</h1>
        <p>{`Here is a paragraph`}</p>
        <TomatoBox />
      </MDXLayout>
    </div>
  );
}

MDXContent.isMDXComponent = true;

1. HTML

<div>
  <main>
    <h1>Hello, world!</h1>
    <p>Here is a paragraph</p>
    <section style="padding:20px;background-color:tomato">
      This is the TomatoBox
    </section>
  </main>
</div>

Features

Something based on the content from the features section on mdxjs.com

Use cases

• Blogging
• Documentation
• Design systems

Testimonials

Might be worthwhile talking to some happy users and get some quotes.

Why?

Something that illustrates or describes the motivation for writing MDX.

• allows you to components, including those elsewhere on the site
• easy to read and write
• decide what elements to render with which components (MDXProvider)

Projects

• MDX Deck
• Docz
• Demoboard

Tooling

Works with the tools you already use

• Next.js
• Gatsby
• Prettier
• Webpack
• Parcel

Plugins

Talk about the remark/rehype ecosystem and interesting things you can do with plugins. Potentially could even show an example.

Showcase/gallery

Images of some awesome MDX sites (#414).

Important links/data

• GitHub
• Current version

Search

Think we can use algolia for this, but would be great to incorporate a search bar since the docs are growing and should grow immensely with the new content planned for v1. Though this doesn't have to be part of the MVP.

[Jarred-Sumner]

Suggestion:

Two-pane layout at the top

Left pane is typed out via something like react-typist (and syntax highlighted) and the right pane is the auto-updated (in sync with typing) rendered result (with a small link at the bottom to view the HTML output)

It animates between ~5 examples of cool things that are possible via MDX and transitions to each one, via the typing animation. The examples are shown in labeled tabs. Ideally, each example is modifiable -- either inline or otherwise. If the user modifies the code, the animation is stopped. If the animation feels too slow, then only animate the first time and subsequently show the other examples without animating.

Left pane:

import TomatoBox from 'tomato-box'

export author = "Fred Flintstone"
export default = props => <main {...props} />

# Hello, world!

Here is a paragraph

<TomatoBox />

Right pane:

Hello, world

Here is a paragraph
🍅

---

If you scroll down, then it shows the sections you mentioned.

Happy to build a prototype of this suggestion you'd like!

[johno]

@Jarred-Sumner I think that'd be _great_! Would be especially awesome if the functionality was style agnostic so we could reuse in a couple places in different contexts. This would overlap with #220 as well.

[johno]

Spent a bit of time this afternoon working on content and an example graphic (written as a component ofc). Here's where I ended up: