Front-End Documentation, Style Guides and the Rise of MDX

Even the best open-source project can fail without comprehensive documentation. Internal documentation is equally crucial, preventing repetitive Q&A and ensuring knowledge continuity even with staff changes. Well-documented coding guidelines promote codebase consistency.

For extensive documentation, Markdown offers a superior alternative to raw HTML. However, Markdown's limitations can be overcome by embedding HTML directly within Markdown files, including custom elements for design systems using web components. For React (and JSX-compatible frameworks like Preact or Vue), MDX provides a seamless integration.

This article provides a high-level overview of documentation and style guide creation tools. While not all utilize MDX, its adoption is rapidly increasing.

Understanding MDX

An .mdx file mirrors standard Markdown syntax but allows the import and embedding of interactive JSX components. Vue component support is currently in alpha. MDX integrates easily with Create React App, and plugins exist for Next.js and Gatsby. Docusaurus version 2 will also feature built-in support.

Docusaurus: A Documentation Powerhouse

Developed by Facebook (excluding React), Docusaurus is utilized by numerous major open-source projects (Redux, Prettier, Gulp, Babel). Its versatility extends beyond front-end documentation. While utilizing React internally, Docusaurus requires no React knowledge for use. It transforms Markdown files into well-structured, visually appealing documentation sites.

Docusaurus sites can incorporate Markdown-based blogs and include Prism.js for seamless syntax highlighting. Its popularity is evident, having been voted the top new tool of 2018 on StackShare.

Alternative Documentation Solutions

While Docusaurus specializes in documentation, numerous alternatives exist. Custom solutions are feasible using various back-end languages, CMSs, or static site generators. React, IBM's design system, Apollo, and Ghost CMS, for example, leverage Gatsby, a versatile static site generator often used for blogs. VuePress is gaining traction within the Vue ecosystem. MkDocs, an open-source static site generator written in Python, offers straightforward YAML configuration. GitBook, a popular paid option, provides free access to open-source and non-profit teams. For simpler internal documentation, GitHub's Markdown rendering capabilities are a viable option.

Component Documentation: Docz, Storybook, and Styleguidist

Style guides and design systems have gained immense popularity. Component-driven frameworks (like React) and associated tools have transformed them from vanity projects into essential resources.

Storybook, Docz, and Styleguidist serve a similar purpose: displaying interactive UI components and documenting their APIs. Managing numerous components with varying states and styles necessitates a centralized catalog for discoverability and reuse. Style guides provide easily searchable overviews, promoting visual consistency and preventing redundant work.

These tools simplify the review of different component states, overcoming the challenges of reproducing all states within a live application. Isolated component development allows for mocking hard-to-reach states (e.g., loading states).

Dan Green's comments on Storybook's benefits apply equally to Docz and Styleguidist:

“Storybook has simplified collaboration between design and engineering. It eliminates the need for complex setup (Docker containers, etc.). For Wave, we manage components only visible during short-lived, complex processes (e.g., loading screens). Before Storybook, managing these components was difficult. Now, Storybook provides an isolated environment, accessible to designers and PMs, streamlining sprint demos.”

– Dan Green, Wave Financial

Beyond visualizing states and listing props, written content (design rationale, use cases, user-testing results) enhances component documentation. Markdown's accessibility makes it ideal for collaborative documentation between designers and developers. Docz, Styleguidist, and Storybook seamlessly integrate Markdown with components.

Docz

Currently React-only (with planned support for Preact, Vue, and web components), Docz (14,000 GitHub stars) offers user-friendly functionality. It provides <playground></playground> and <props></props> components, directly used within .mdx files.

import { Playground, Props } from "docz";
import Button from "../src/Button";

## You can _write_ **markdown**
### You can import and use components

<playground>
  <button>click</button>
</playground>

Wrapping React components with <playground></playground> creates embedded interactive previews. <props></props> displays component props, default values, and required status.

<props of="{Button}"></props>

Docz's MDX-based approach is intuitive and efficient, offering excellent Gatsby integration.

Styleguidist

Styleguidist uses Markdown code blocks (triple backticks) within standard .md files instead of MDX.

```js
 console.log('clicked')

<code></code>

<code>>Push Me</code>

Code blocks tagged js, jsx, or javascript render as interactive React components. The code is editable, providing instant visual feedback. Styleguidist automatically generates prop tables from PropTypes, Flow, or TypeScript declarations. It supports React and Vue.

Storybook

Storybook (36,000 GitHub stars) is a UI component development environment. Instead of Markdown/MDX, it uses JavaScript files for stories (representing component states).

storiesOf('Button', module)
  .add('disabled', () => (
    <button disabled>lorem ipsum</button>
  ))

Storybook's approach is less intuitive than Docz and Styleguidist. However, its popularity and extensive framework support (React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte, HTML) are noteworthy. Documentation currently requires addons, but future releases will incorporate MDX, inspired by Docz.

# Button

Some _notes_ about your button written with **markdown syntax**.


<button>lorem ipsum</button>

Storybook's upcoming Docs feature promises significant improvements.

Conclusion

The value of pattern libraries is widely acknowledged. Well-executed libraries promote visual consistency and product cohesion. While these tools don't replace design and CSS expertise, Docz, Storybook, and Styleguidist provide excellent solutions for communicating design systems effectively within organizations.

The above is the detailed content of Front-End Documentation, Style Guides and the Rise of MDX. For more information, please follow other related articles on the PHP Chinese website!