Beyond Markdown

Presentation

Page 1 of 48

Introduction

In the rapidly evolving world of software development, effective communication and dissemination of information are critical to the success of any project. For developers, documentation websites serve as an invaluable resource, providing the knowledge and guidance necessary to create outstanding products. Today, we have a number of tools that we use to create documentation and they range from services like Notion to GitBook.

As technology advances, the traditional tools used for documentation have proven their worth, but it is essential to continually explore new methods to enhance the developer experience. Recently, we've been moving towards "Docs as code" for a solution to the limitations that the products impose. "Docs as code" is a way technical writers & developers create and publish documentation. Moreover, it involves the same tools & processes used to build & ship software.

Embracing Docs as code within your teams solves a lot of problems but it only solves a lot of problems for development teams. How about the people that are reading the docs? How can we create solutions for them?

One such innovation that can change the way we interact with documentation workflows and solve problems for the readers of our docs is known as MDX. MDX is a superset of Markdown that allows us to embed JSX within our markdown content. The MDXJS website puts it best when they say that MDX is Markdown for the component era.

Going beyond Markdown

The surprising thing is that MDX within our docs is actually nothing new!! Most often, when docs say they support MDX, they tend to just build components that add stylistic elements and a few features. Stylistic elements like the one below are not supported within regular markdown or any flavour of markdown for that matter.

This is really cool and sometimes a necessity but can we do anything else with MDX? Recall that MDX is a superset of markdown that allows us to embed JSX within our markdown content. The important keyword here is JSX -- as it allows us to seamlessly blend the expressive power of React components with the simplicity of markdown syntax.

It allows us to do things like directly embed the quiz component or the live coding environment below directly into our markdown content.

This is really cool but the question then becomes -- How does it help developers?

DND kit

Imagine we were reading the documentation for a library we want to implement into our project. In this case, let's say we were working with the Drag & Drop library from DND Kit.

Their documentation is really well laid out in my opinion, however, I think it can be enhanced with the addition of interactive components.

The documentation portion that goes through the different collision detection algorithms gives a detailed explanation of how each algorithm affects the DND system. Although the DND docs provide images for this integration, for some it may still be hard to visualize. To combat this DND kit also has a playground where you can see all the interactions and test all the different configurations of the library. However, this involves you opening a separate window/tab thus it introduces more context switching.

Using MDX, we can embed a live coding playground to see how the code is implemented and also see the result of any changes that are made to the code. Let's look at our implementation below:

import "./styles.css";
import { useCallback, useState } from "react";

import {
  DndContext,
  rectIntersection,
  pointerWithin,
  closestCenter,
  closestCorners
} from "@dnd-kit/core";
import Draggable from "./Draggable";
import Droppable from "./Droppable";

import useEstablishDndSensors from "./hooks/use-dnd-sensors";

export default function App() {
  const sensors = useEstablishDndSensors();

  const [items, setItems] = useState({
    content: "drag me",
    isDropped1: false
  });

  const handleDragEnd = useCallback((e) => {
    const { over } = e;
    if (over && over.id === "droppable") {
      setItems((prev) => ({ ...prev, isDropped1: true }));
    }
  }, []);

  return (
    <div className="App">
      <DndContext
        onDragEnd={handleDragEnd}
        onDragCancel={() =>
          setItems((prev) => ({ ...prev, isDropped1: false }))
        }
        sensors={sensors}
        collisionDetection={pointerWithin}
      >
        <div className="boxes">
          <Droppable id="1">
            {items.isDropped1 ? (
              <Draggable
                droppableItem={{ id: "1", content: "left box there" }}
              />
            ) : (
              <p className="droppedElement">Sorted List</p>
            )}
          </Droppable>
        </div>
        {!items.isDropped1 && (
          <Draggable droppableItem={{ id: "1", content: "hello there" }} />
        )}
      </DndContext>
    </div>
  );
}

Side tangents

MDX also allows you to hide and reveal side tangents. This is very useful in documentation as you the writer gains the ability to include information that would be helpful to the reader but necessary for the particular section. In this case, if the reader already knows the information then they can skip the section but if they want to learn more then they can expand the block quote.

Let's try it out below:

How we learn

The suggestion to expand on how we include MDX in our docs has a lot to do with how we learn!! There are two common approaches to learning something

Passive learning -- Quietly absorbing information and knowledge without engaging with the learning material
Active learning -- Method of learning that ask students to engage with the learning material by thinking, discussing, and investigating the material.

To be fair, when we are using documentation to build products, we actually engaging in active learning. We may often read the docs of a particular product and then try to think about how we could include that feature in our product. We may even discuss it with a colleague or friend or investigate other approaches to working with that feature.

It's really cool that we are already engaging with active learning when working with docs but I think expanding on how we include MDX in our docs will allow us to more efficiently blend the two approaches of learning and bring them into one location -- our docs.

How do we get started?

We've talked about why going beyond markdown is important and the experiences we can create. So the question now is: Where do we begin?

There are two common approaches:

We could build our own platform
Start from a template

There are different libraries involved with each of these approaches so let's take a look!

Build our own platform

Within this section there are three popular options that we can go with when integrating MDX into our application. They include:

The official way, @next/mdx
Kent C Dodds' mdx-bundler
Hashicorp's next-mdx-remote

All libraries are really good but personally, I've only experimented with mdx-bundler and next-mdx-remote.

Start from a template

We could also start from a template and the involve

How do we deploy

There are many platforms we can deploy our newly created MDX project too and such platforms are/not limited to:

GitHub Pages -- using actions
Vercel
Netlify
AWS

Although Vercel and Netlify support one-click deploys out of the box, this can be set up with GitHub pages and AWS as well!

Wrapping up

I hope you now have a clear understanding of why embracing MDX and going beyond the addition of simple components is a game-changer for documentation websites. Further, I hope that through the presentation and article, I've inspired you to unlock the full potential of MDX to provide an immersive and productive learning experience for developers. Thereby, making documentation a joy to read, use, and contribute to. Together, let's enhance the developer experience and take our documentation to the next level with MDX and GitHub Pages

Practice problems

PSSSST! Hey you! Yaa you! Enjoyed the article and presentation?? Here's a fun little exercise for you to try out! 👀

Exercise

These are a series of questions or mini-games that are associated with the article you just finished reading! They are meant to help solidify the concepts talked about in this article. Have fun!

on this page

presentation introduction going beyond markdown dnd kit side tangents how we learn how do we get started?build our own platform start from a template how do we deploy wrapping up practice problems

106 views