In December 2021, I delivered a talk at React Conf about how we could leverage the tools we have at our disposal, such as React and MDX, to introduce more active learning experiences to our documentation and articles.

This is a follow-up to that talk. Below, you'll find some background thoughts, a curated list of docs and personal blogs that are merging the lines between static and interactive; passive and active. As well as tools and resources to inspire you to build your own.

Background

I've always loved reading, but when I was learning to code, I often struggled reading technical docs and articles. I used to think it was because of my lack of experience (which was partly true of course) but now that I'm a Developer Advocate, I'm starting to understand that effective knowledge sharing isn't just dependant on the consumer, it's also up to the creator and how clearly they're able to transfer information.

Regardless of your level of experience, your ability to understand new topics will depend on external factors such as how well and clear the information is presented.

When we were children, we learned through play and interaction. Learning felt effortless when it was fun. But as we have grown older, our learning methods changed; from active (interacting, playing, building) to passive (reading, watching, listening) learning.

As the web emerged as a medium, we started sharing knowledge through text and images. Technology progressed and we added audio and video to the mix. Each of these types of content certainly have their place, but you may have noticed that they still primarily used for passive learning.

One under-utilised opportunity for active learning the web allows is interaction. Creating interactive content is both more time consuming and more technically challenging. But if active learning is more effective, I think it's worth a shot.

As developers who are already creating rich and interactive components as part of our applications, we're perfectly positioned to create more effective learning experiences through "interactive playgrounds".

Inspiration

Docs

• React Docs
• Svelte Tutorial
• nivo Docs

Articles

• "Build your own React" by Rodrigo Pombo
• "What does 100% means in CSS?" by Amelia Wattenberger
• "Waveforms" by Josh Comeau
• "Making things move" by Varun Vachhar
• "Noise in Creative Coding" by Varun Vachhar
• "Which Blend Mode?" by Chris Nicholas
• "Dark Mode by Local Sunlight" by Chris Nicholas
• "Moving along a curved path in CSS with layered animation" by Tobias Ahlin
• "How do arrays work?" by Nanda
• "Lights and Shadows" by Bartosz Ciechanowski
• Advanced animation patterns with Framer Motion - by Maxime Heckel
• How to remember things - by Nicky Case

Collections

• Pudding.cool
• Worrydream by Bret Victor
• Explorable Explanations

Tutorials

• Interactive Documentation at scale using MDX and Next.js - Jeff Escalante
• The X in MDX - Rodrigo Pombo
• Markdown/MDX with Next.js - Lee Rob
• Using MDX with Next.js - Next.js Docs
• Code blocks, but better - Pedro Duarte

Tools

Out-of-the-box solutions:

• Code Hike - easily build code tutorials with MDX and React.
• Docusaurus - quickly build documentation sites.
• Nextra - a Next.js static site generator.

Custom solutions:

If you're looking to build your own custom solution, there are a couple of different tools and resources that help with the implementation of MDX.

• next/mdx - allows you to create .mdx pages extension inside your Next.js pages/ folder. Example.
• mdx-loader - a webpack loader to convert Markdown files into React components. Example.
• next-mdx-remote - a set of utilities that allow you to load and hydrate MDX with getStaticProps() and getServerSideProps(). Example.
• mdx-bundler - compile and bundle MDX files. Examples with Next.js and Remix.
• contentlayer - import MDX and CMS content into your project. Example.
• gatsby-plugin-mdx - The official integration for using MDX with Gatsby. Example.
• MDX Pretty Code - Simply beautiful syntax highlighting for your MDX docs
• Sandpack - a toolkit for building live coding experiences that run fully in the browser.

In addition to the tools above, you may want to consider looking into plugins that allow you to intercept and manipulate the transformation between markdown and your final output (JSX, JS or HTML).

• remark
• rehype

Thank you to everyone who shared their favourite examples with me on Twitter and if you've seen any exceptional examples that are not listed here, PRs are welcome.