{"id":34791,"date":"2019-10-31T22:00:25","date_gmt":"2019-10-31T19:00:25","guid":{"rendered":"https:\/\/prohoster.info\/blog\/zhivye-gajdlajny-mdx-i-drugie-frejmvorki\/"},"modified":"2019-10-31T22:00:25","modified_gmt":"2019-10-31T19:00:25","slug":"zhivye-gajdlajny-mdx-i-drugie-frejmvorki","status":"publish","type":"post","link":"https:\/\/prohoster.info\/en\/blog\/administrirovanie\/zhivye-gajdlajny-mdx-i-drugie-frejmvorki","title":{"rendered":"Live guidelines \u2014 MDX and other frameworks","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

You may have the best open-source project, but without good documentation, it is likely to never take off. Good documentation in the office allows you to avoid answering the same questions repeatedly. It also ensures that people can understand the project if key employees leave the company or roles change. Live guidelines help maintain data integrity. <\/p>\n

<\/a><\/noindex><\/p>\n

If you need to write a lengthy text, Markdown is an excellent alternative to HTML. Sometimes, Markdown's syntax is not enough. In that case, we can use HTML within it. For example, custom elements. So if you're building a design system with native web components, they can easily be included in text documentation. If you're using React (or any other JSX framework such as Preact or Vue), you can do the same using MDX. <\/p>\n

<\/p>\n

This article is a broad overview of tools for writing documentation and creating guidelines. Not all tools listed here use MDX, but it is increasingly being included in documentation tools.<\/p>\n

<\/p>\n

What is MDX?<\/h2>\n

<\/p>\n

File .mdx<\/code> has the same syntax as Markdown but allows you to import interactive JSX components and embed them into your content. Support for Vue components is currently in alpha. To get started with MDX, simply install 'Create React App'. There are plugins available for Next.js and Gatsby. The next version of Docusaurus (version 2) will also have built-in support.<\/p>\n

<\/p>\n

Writing Documentation with Docusaurus<\/h2>\n

<\/p>\n

Docusaurus was created by Facebook. They use it for every open-source project except React. Outside the company, it is used by Redux, Prettier, Gulp, and Babel.<\/p>\n

<\/p>\n

\"LiveProjects that use Docusaurus.<\/em><\/p>\n

<\/p>\n

Docusaurus can be used for writing any<\/em> documentation, not only for describing the frontend. It is built on React, but you don't need to be familiar with it to use it. It takes your Markdown files, a pinch of magic, and you have well-structured, formatted, and readable documentation with a beautiful design ready. <\/p>\n

<\/p>\n

\"Live
\nYou can view the standard Docusaurus template on the Redux website.<\/em><\/p>\n

<\/p>\n

Websites created using Docusaurus can also include a blog based on Markdown. Prism.js is integrated for syntax highlighting right away. Despite Docusaurus being relatively new, it was recognized as the best tool of 2018 on StackShare. <\/p>\n

<\/p>\n

Other content creation options<\/h2>\n

<\/p>\n

Docusaurus is specifically designed for creating documentation. Of course, there are a million and one ways to make a site \u2014 you can deploy your own solution in any language, CMS, or use a static site generator.<\/p>\n

<\/p>\n

For example, the documentation for React, IBM's design system, Apollo, and Ghost CMS uses Gatsby \u2014 a static site generator often used for blogs. If you're working with Vue, VuePress is a great option. Another alternative is to use a generator written in Python \u2014 MkDocs. It is open-source and configured with a single YAML file. GitBook is also a good choice, but it's free only for open and non-commercial teams. You can also simply upload markdown files using git and work with them on GitHub. <\/p>\n

<\/p>\n

Documenting components: Docz, Storybook, and Styleguidist<\/h2>\n

<\/p>\n

Guidelines, design systems, component libraries \u2014 whatever you call them, they've become quite popular lately. The emergence of component frameworks like React and the tools mentioned here has allowed them to evolve from vanity projects into useful tools. <\/p>\n

<\/p>\n

Storybook, Docz, and Styleguidist all do the same thing: display interactive elements and document their APIs. A project can have dozens or even hundreds of components \u2014 all with various states and styles. If you want components to be reused, people need to know they exist. Cataloging the components is sufficient for this. Guidelines provide a searchable overview of all your components. This helps maintain visual consistency and avoids redundant work.<\/p>\n

<\/p>\n

These tools provide a convenient way to view various states. It can be challenging to reproduce every state of a component in the context of a real application. Instead of clicking through a real app, it is advisable to develop a separate component. You can model hard-to-reach states (for example, a loading state). <\/p>\n

<\/p>\n

Alongside the visual demonstration of various states and a list of properties, it is often necessary to write a general description of the content \u2014 design rationales, use cases, or descriptions of user testing results. Markdown is very easy to learn \u2014 ideally, the guidelines should be a shared resource for designers and developers. Docz, Styleguidist, and Storybook provide a way to easily mix Markdown with components.<\/p>\n

<\/p>\n

Docz<\/h2>\n

<\/p>\n

Currently, Docz only works with React, but active work is underway to support Preact, Vue, and web components. Docz is the freshest of the three tools, having gathered over 14,000 stars on GitHub. Docz features two components \u2014 <Playground><\/code> and < Props ><\/code>. They are imported and used in files .mdx<\/code>. <\/p>\n

<\/p>\n

import { Playground, Props } from \"docz\";\nimport Button from \"..\\\/src\\\/Button\";\n\n## You can _write_ **markdown**\n### You can import and use components\n\n