Live guidelines - MDX and other frameworks

You may have a better open source project, but if it doesn’t have good documentation, it’s likely that it will never take off. In the office, good documentation will allow you not to answer the same questions. The documentation also ensures that people can understand the project if key people leave the company or roles change. Live guidelines help ensure data integrity.

If you need to write a long text, Markdown is a great alternative to HTML. Sometimes the Markdown syntax is not enough. In this case, we can use HTML inside it. For example, custom elements. Therefore, if you build a design system with native web components, they are easy to include in the text documentation. If you use React (or any other JSX framework, for example, Preact or Vue), you can do the same with MDX.

This article is a broad overview of the tools for writing documentation and creating a guideline. Not all the tools listed here use MDX, but it is increasingly being included in documentation tools.

What is MDX?

The .mdx file has the same syntax as Markdown, but allows you to import interactive JSX components and embed them into your content. Support for Vue components to be in alpha. To start working with MDX, it’s enough to install the "Create React App". There are plugins for Next.js and Gatsby. The next version of Docusaurus (version 2) will also have built-in support.

Writing Documentation with Docusaurus

Docusaurus wrote on Facebook. They use it on every open source project, except React. Outside the company, Redux, Prettier, Gulp and Babel use it.

Projects that use Docusaurus.

Docusaurus can be used to write any documentation, not only to describe the frontend. He has React under the hood, but in order to use it, it’s not necessary to be familiar with it. It takes your Markdown files, pinch magic and well-structured, formatted and readable documentation with a beautiful design ready.

On the Redux site you can see the standard template Docusaurus

Sites created with Docusaurus may also include a blog based on Markdown. For syntax highlighting, Prism.js is immediately connected. Despite the fact that Docusaurus appeared relatively recently, he was recognized as the best tool of 2018 at StackShare.

Other content creation options

Docusaurus is specially designed for creating documentation. Of course, there is a million and one ways to make a website - you can deploy your own solution in any language, CMS or use a static site generator.

For example, the documentation for React, the IBM design system, Apollo, and Ghost CMS use Gatsby, a static site generator that is often used for blogs. If you're working with Vue, then VuePress will be a good option for you. Another option is to use a generator written in Python - MkDocs. It is open and configured using a single YAML file. GitBook is also a good option, but it is free only for open and non-commercial teams. And you can just upload mardown files using git and work with them on Github.

Component Documentation: Docz, Storybook and Styleguidist

Guidelines, system design, component libraries — whatever you call them, but this has become very popular lately. The emergence of component frameworks, such as React and the tools mentioned here, made it possible to turn them from vanity projects into useful tools.

Storybook, Docz and Styleguidist - do the same thing: display interactive elements and document their API. A project can have dozens or even hundreds of components - all with different states and styles. If you want components to be reused, people need to know that they exist. To do this, it is enough to catalog the components. Guidelines provide a searchable overview of all your components. This helps maintain visual consistency and avoid re-work.

These tools provide a convenient way to view various states. It can be difficult to reproduce every state of a component in the context of a real application. Instead of clicking on a real application, you should develop a separate component. You can model hard-to-reach states (for example, download status).

Along with a visual demonstration of various states and a list of properties, it is often necessary to write a general description of the content — design justifications, use cases, or a description of user testing results. Markdown is very easy to learn - ideally, guidelines should be a shared resource for designers and developers. Docz, Styleguidist and Storybook offer a way to easily mix Markdown with components.

Docz

Now Docz works only with React, but there is an active work on support for Preact, Vue and web components. Docz is the freshest of the three instruments, but on Github he was able to collect more than 14,000 stars. Docz presents two components - <Playground> and < Props > . They are imported and used in .mdx files.

 import { Playground, Props } from "docz"; import Button from "../src/Button"; ## You can _write_ **markdown** ### You can import and use components <Button>click</Button> 

You can wrap your own React components with <Playground> to create an analogue of the built-in CodePen or CodeSandbox — that is, you can see your component and edit it.

 <Playground> <Button>click</Button> </Playground> 

<Props> will show all available properties for this React component, default values ​​and whether the property is required.

 <Props of={Button} /> 

Personally, I consider this MDX based approach to be the easiest to understand and the easiest to work with.

If you're a fan of the Gatsby static site generator, Docz offers excellent integration.

Styleguidist

As in Docz, examples are written using the Markdown syntax. Styleguidist uses Markdown code blocks (triple quotes) in regular .md files, not in MDX.

 ```js <Button onClick={() => console.log('clicked')>Push Me</Button> 

Markdown code blocks usually just show the code. When using Styleguidist, any code block with a js , jsx or javascript language tag will be displayed as a component of React. As in Docz, the code is editable — you can change properties and instantly see the result.

Styleguidist will automatically create a property sheet from PropTypes, Flow or Typescript ads.

Styleguidist now supports React and Vue.

Storybook

Storybook positions itself as a “UI component development environment”. Instead of writing examples of components inside Markdown or MDX files, you write stories inside Javascript files. History document the specific state of the component. For example, a component may have histories for the boot state and the disabled state ( disabled ).

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

Storybook is much harder than Styleguidist and Docz. But at the same time it is the most popular option, on Github the project has more than 36,000 stars. This is an open source project with 657 participants and full-time staff members. It is used by Airbnb, Algolia, Atlassian, Lyft and Salesforce. Storybook supports more frameworks than competitors — React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte, and plain HTML.

In the future release, there will be chips from Docz and MDX is being introduced.

 # Button Some _notes_ about your button written with **markdown syntax**. <Story name="disabled"> <Button disabled>lorem ipsum</Button> </Story> 

The new Storybook features will appear gradually over the next few months, and it seems that this will be a big step forward.

Results

The benefits of the pattern library are exalted in millions of articles on Medium. When done well, they facilitate the creation of related products and the maintenance of identity. Of course, none of these tools will magically create a design system. This requires careful design and CSS design. But when it comes time to make the design available for the entire company, Docz, Storybook and Styleguidist are great options.

From the translator. This is my first experience on Habré. If you find any inaccuracies, or there are suggestions for improving the article - write in a personal.