라이브 지침 - MDX 및 기타 프레임워크

최고의 오픈 소스 프로젝트를 가질 수 있지만, 좋은 문서가 없으면 성공하지 못할 가능성이 높습니다. 사무실에서는 문서를 잘 작성하면 동일한 질문에 답할 수 없습니다. 문서화는 주요 직원이 회사를 떠나거나 역할이 변경되는 경우 사람들이 프로젝트를 이해할 수 있도록 보장합니다. 생활 지침은 데이터 무결성을 보장하는 데 도움이 됩니다.

긴 텍스트를 작성해야 하는 경우 Markdown은 HTML의 훌륭한 대안입니다. 때때로 Markdown 구문만으로는 충분하지 않습니다. 이 경우 내부에 HTML을 사용할 수 있습니다. 예를 들어 맞춤 요소가 있습니다. 따라서 기본 웹 구성 요소를 사용하여 디자인 시스템을 구축하는 경우 해당 구성 요소를 텍스트 문서에 쉽게 포함할 수 있습니다. React(또는 Preact나 Vue와 같은 다른 JSX 프레임워크)를 사용하는 경우 MDX에서도 동일한 작업을 수행할 수 있습니다.

이 문서는 문서 작성 및 지침 작성을 위한 도구에 대한 광범위한 개요입니다. 여기에 나열된 모든 도구가 MDX를 사용하는 것은 아니지만 문서화 도구에 MDX가 점점 더 많이 포함되고 있습니다.

MDX란 무엇입니까?

파일 .mdx Markdown과 동일한 구문을 사용하지만 대화형 JSX 구성 요소를 가져와 콘텐츠에 포함할 수 있습니다. Vue 구성 요소에 대한 지원은 알파 버전입니다. MDX 작업을 시작하려면 “Create React App”을 설치하세요. Next.js 및 Gatsby용 플러그인이 있습니다. Docusaurus의 다음 버전(버전 2)도 기본적으로 지원됩니다.

Docusaurus로 문서 작성하기

Docusaurus는 Facebook에 글을 썼습니다. 그들은 React를 제외한 모든 오픈 소스 프로젝트에서 이를 사용합니다. 회사 외부에서는 Redux, Prettier, Gulp 및 Babel에서 사용됩니다.

Docusaurus를 사용하는 프로젝트.

Docusaurus를 사용하여 글을 쓸 수 있습니다. 모든 문서는 프런트엔드를 설명하는 것뿐만 아니라 내부적으로 React가 있지만 사용하기 위해 익숙해질 필요는 없습니다. Markdown 파일을 사용하면 마술처럼 잘 구조화되고 형식화되고 읽기 쉬운 아름다운 디자인의 문서가 준비됩니다.

Redux 웹사이트에서 표준 Docusaurus 템플릿을 볼 수 있습니다.

Docusaurus로 구축된 웹사이트에는 Markdown 기반 블로그도 포함될 수 있습니다. Prism.js는 구문 강조를 위해 즉시 연결됩니다. Docusaurus가 비교적 최근에 등장했음에도 불구하고 StackShare에서는 2018년 최고의 도구로 인정받았습니다.

기타 콘텐츠 생성 옵션

Docusaurus는 문서 작성을 위해 특별히 설계되었습니다. 물론 웹사이트를 만드는 방법은 수없이 많습니다. 모든 언어, CMS로 자신만의 솔루션을 배포하거나 정적 사이트 생성기를 사용할 수 있습니다.

예를 들어 React, IBM 디자인 시스템, Apollo 및 Ghost CMS에 대한 문서에서는 블로그에 자주 사용되는 정적 사이트 생성기인 Gatsby를 사용합니다. Vue로 작업하는 경우 VuePress가 좋은 선택입니다. 또 다른 옵션은 Python으로 작성된 생성기인 MkDocs를 사용하는 것입니다. 오픈 소스이며 단일 YAML 파일을 사용하여 구성됩니다. GitBook도 좋은 옵션이지만 공공 및 비상업적 팀에게만 무료입니다. Git을 사용하여 간단하게 mardown 파일을 업로드하고 Github에서 작업할 수도 있습니다.

문서화 구성 요소: Docz, Storybook 및 Styleguidist

지침, 시스템 설계, 구성 요소 라이브러리 등 무엇이라고 부르든 최근에는 매우 인기가 높아지고 있습니다. React와 같은 구성요소 프레임워크와 여기에 언급된 도구의 출현으로 이를 허영심 프로젝트에서 유용한 도구로 변모시켰습니다.

Storybook, Docz 및 Styleguidist는 모두 동일한 작업을 수행합니다. 즉, 대화형 요소를 표시하고 해당 API를 문서화합니다. 프로젝트에는 상태와 스타일이 서로 다른 수십 또는 수백 개의 구성 요소가 있을 수 있습니다. 구성요소를 재사용하려면 사람들이 해당 구성요소가 존재한다는 사실을 알아야 합니다. 이렇게 하려면 구성요소를 카탈로그화하면 됩니다. 지침은 모든 구성 요소에 대한 개요를 쉽게 찾을 수 있도록 제공합니다. 이는 시각적 일관성을 유지하고 반복적인 작업을 방지하는 데 도움이 됩니다.

이러한 도구는 다양한 상태를 볼 수 있는 편리한 방법을 제공합니다. 실제 애플리케이션 환경에서 구성 요소의 각 상태를 재현하는 것은 어려울 수 있습니다. 실제 애플리케이션을 클릭하는 대신 별도의 구성 요소를 개발하는 것이 좋습니다. 도달하기 어려운 상태(예: 로딩 상태)를 시뮬레이션할 수 있습니다.

다양한 상태 및 속성 목록의 시각적 데모와 함께 콘텐츠에 대한 일반적인 설명(설계 근거, 사용 사례 또는 사용자 테스트 결과 설명)을 작성해야 하는 경우가 많습니다. 마크다운은 배우기가 매우 쉽습니다. 이상적으로 지침은 디자이너와 개발자가 공유하는 리소스여야 합니다. Docz, Styleguidist 및 Storybook은 Markdown을 구성 요소와 쉽게 혼합할 수 있는 방법을 제공합니다.

문서

현재 Docz는 React에서만 작동하지만 Preact, Vue 및 웹 구성 요소를 지원하기 위한 활발한 작업이 진행 중입니다. Docz는 세 가지 도구 중 가장 최신 도구이지만 Github에서 14개 이상의 별을 수집했습니다. Docz는 두 가지 구성 요소를 소개합니다. <Playground> и < Props >. 파일로 가져와 사용됩니다. .mdx.

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

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

<Button>click</Button>

자신만의 React 컴포넌트를 다음과 같이 래핑할 수 있습니다. <Playground>내장된 CodePen 또는 CodeSandbox의 아날로그를 생성합니다. 즉, 구성 요소를 보고 편집할 수 있습니다.

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

<Props> 특정 React 구성 요소에 사용 가능한 모든 속성, 기본값 및 속성이 필요한지 여부를 표시합니다.

<Props of={Button} />

개인적으로 저는 이 MDX 기반 접근 방식이 가장 이해하기 쉽고 작업하기 가장 쉽다고 생각합니다.

Gatsby 정적 사이트 생성기의 팬이라면 Docz가 훌륭한 통합 기능을 제공합니다.

스타일 가이드

Docz와 마찬가지로 예제는 Markdown 구문을 사용하여 작성됩니다. Styleguidist는 일반 파일에서 Markdown 코드 블록(삼중따옴표)을 사용합니다. .md MDX가 아닌 파일.

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

Markdown의 코드 블록은 일반적으로 코드만 표시합니다. Styleguidist를 사용할 때 언어 태그가 있는 모든 코드 블록 js, jsx 또는 javascript React 구성 요소로 렌더링됩니다. Docz와 마찬가지로 코드도 편집 가능합니다. 속성을 변경하고 결과를 즉시 확인할 수 있습니다.

Styleguidist는 PropTypes, Flow 또는 Typescript 선언에서 속성 테이블을 자동으로 생성합니다.

Styleguidist는 현재 React와 Vue를 지원합니다.

스토리 북

스토리북은 'UI 컴포넌트 개발 환경'으로 자리매김합니다. Markdown 또는 MDX 파일 내에 예제 구성 요소를 작성하는 대신 다음을 작성합니다. 역사 자바스크립트 파일 내부. 이야기 구성 요소의 특정 상태를 문서화합니다. 예를 들어 구성 요소에는 로드된 상태와 비활성화된 상태에 대한 기록이 있을 수 있습니다(사용).

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

Storybook은 Styleguidist 및 Docz보다 훨씬 더 복잡합니다. 그러나 동시에 이것은 가장 인기 있는 옵션이며 이 프로젝트는 Github에서 36개 이상의 별을 받았습니다. 000명의 기여자와 정규 직원이 참여하는 오픈 소스 프로젝트입니다. Airbnb, Algolia, Atlassian, Lyft 및 Salesforce에서 사용됩니다. Storybook은 React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte 및 일반 HTML 등 경쟁사보다 더 많은 프레임워크를 지원합니다.

향후 릴리스에는 Docz 및 MDX의 기능이 도입될 예정입니다.

# Button

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

<Story name="disabled">
  <Button disabled>lorem ipsum</Button>
</Story>

Storybook의 새로운 기능은 앞으로 몇 달에 걸쳐 점진적으로 출시될 예정이며 이는 큰 진전이 될 것으로 보입니다.

결과

패턴 라이브러리의 이점은 Medium의 수백만 개의 기사에서 극찬되었습니다. 잘 수행되면 관련 제품을 만들고 아이덴티티를 유지하는 것이 더 쉬워집니다. 물론, 이러한 도구 중 어느 것도 마법처럼 디자인 시스템을 생성하지는 않습니다. 이를 위해서는 신중한 디자인과 CSS가 필요합니다. 그러나 회사 전체가 액세스할 수 있는 디자인 시스템을 만들 때가 되면 Docz, Storybook 및 Styleguidist가 훌륭한 선택입니다.

번역가로부터. 이것이 Habré에 대한 나의 첫 경험입니다. 부정확한 내용을 발견했거나 기사 개선을 위한 제안이 있는 경우 개인 메시지로 저에게 편지를 보내주세요.

출처 : habr.com