دستورالعمل های زنده - MDX و سایر چارچوب ها

شما می‌توانید بهترین پروژه منبع باز را داشته باشید، اما اگر مستندات خوبی نداشته باشد، به احتمال زیاد هرگز راه نخواهد افتاد. در دفتر، مستندات خوب شما را از پاسخ دادن به سوالات مشابه باز می دارد. مستندات همچنین تضمین می‌کند که اگر کارکنان کلیدی شرکت را ترک کنند یا نقش‌هایشان تغییر کند، افراد می‌توانند پروژه را درک کنند. دستورالعمل های زندگی به اطمینان از یکپارچگی داده ها کمک می کند.

اگر نیاز به نوشتن متن طولانی دارید، Markdown یک جایگزین عالی برای HTML است. گاهی اوقات دستور Markdown کافی نیست. در این صورت می توانیم از HTML داخل آن استفاده کنیم. به عنوان مثال، عناصر سفارشی. بنابراین، اگر در حال ساختن یک سیستم طراحی با اجزای وب بومی هستید، می توان آنها را به راحتی در اسناد متنی گنجاند. اگر از React (یا هر چارچوب JSX دیگری مانند Preact یا Vue) استفاده می کنید، می توانید همین کار را با MDX انجام دهید.

این مقاله مروری کلی بر ابزارهای نوشتن اسناد و ایجاد دستورالعمل است. همه ابزارهای فهرست شده در اینجا از MDX استفاده نمی کنند، اما به طور فزاینده ای در ابزارهای مستندسازی گنجانده می شود.

MDX چیست؟

پرونده .mdx دارای نحو مشابه Markdown است، اما به شما امکان می دهد اجزای تعاملی JSX را وارد کنید و آنها را در محتوای خود جاسازی کنید. پشتیبانی از اجزای Vue به صورت آلفا است. برای شروع کار با MDX، فقط "Create React App" را نصب کنید. افزونه هایی برای Next.js و Gatsby وجود دارد. نسخه بعدی Docusaurus (نسخه 2) نیز پشتیبانی بومی خواهد داشت.

نوشتن مستندات با Docusaurus

Docusaurus در فیس بوک نوشت. آنها از آن در هر پروژه منبع باز به جز React استفاده می کنند. خارج از شرکت توسط Redux، Prettier، Gulp و Babel استفاده می شود.

پروژه هایی که از Docusaurus استفاده می کنند.

از Docusaurus می توان برای نوشتن استفاده کرد любой مستندات، نه تنها برای توصیف نمای ظاهری. React زیر کاپوت دارد، اما برای استفاده از آن نیازی به آشنایی با آن نیست. فایل‌های Markdown شما را می‌گیرد، مقداری جادو و مستندات با ساختار، قالب‌بندی و خوانا با طراحی زیبا آماده است.

در وب سایت Redux می توانید قالب استاندارد Docusaurus را مشاهده کنید

وب‌سایت‌هایی که با Docusaurus ساخته می‌شوند می‌توانند شامل یک وبلاگ مبتنی بر Markdown نیز باشند. Prism.js بلافاصله برای برجسته کردن نحو متصل می شود. با وجود این واقعیت که Docusaurus نسبتاً اخیراً ظاهر شد، به عنوان بهترین ابزار سال 2018 در StackShare شناخته شد.

سایر گزینه های ایجاد محتوا

Docusaurus به طور خاص برای ایجاد اسناد طراحی شده است. البته، یک میلیون و یک راه برای ایجاد یک وب سایت وجود دارد - شما می توانید راه حل خود را به هر زبانی، CMS، یا از یک مولد سایت استاتیک استفاده کنید.

به عنوان مثال، مستندات برای React، سیستم طراحی IBM، Apollo و Ghost CMS از Gatsby استفاده می کنند - یک مولد سایت ایستا که اغلب برای وبلاگ ها استفاده می شود. اگر با Vue کار می کنید، VuePress گزینه خوبی برای شما است. گزینه دیگر استفاده از یک ژنراتور نوشته شده در پایتون - MkDocs است. منبع باز است و با استفاده از یک فایل YAML پیکربندی شده است. GitBook نیز گزینه خوبی است، اما فقط برای تیم های عمومی و غیر تجاری رایگان است. همچنین می توانید به سادگی فایل های mardown را با استفاده از Git آپلود کنید و با آنها در Github کار کنید.

اجزای مستندسازی: Docz، Storybook و Styleguidist

دستورالعمل ها، طراحی سیستم، کتابخانه های مؤلفه - هر چه که آنها را بنامید، اخیراً بسیار محبوب شده است. ظهور فریمورک های کامپوننت مانند React و ابزارهایی که در اینجا ذکر شد، آنها را از پروژه های غرور به ابزارهای مفید تبدیل کرده است.

Storybook، Docz و Styleguidist همه یک کار را انجام می دهند: نمایش عناصر تعاملی و مستندسازی API آنها. یک پروژه می تواند ده ها یا حتی صدها جزء داشته باشد - همه با حالت ها و سبک های مختلف. اگر می‌خواهید از اجزا استفاده مجدد شود، مردم باید بدانند که وجود دارند. برای انجام این کار، به سادگی کامپوننت ها را فهرست بندی کنید. دستورالعمل ها یک نمای کلی آسان برای یافتن همه اجزای شما ارائه می دهند. این به حفظ قوام بصری و جلوگیری از کارهای تکراری کمک می کند.

این ابزارها راه مناسبی برای مشاهده وضعیت های مختلف فراهم می کنند. بازتولید هر حالت از یک جزء در زمینه یک برنامه واقعی می تواند دشوار باشد. به جای کلیک بر روی برنامه واقعی، ارزش توسعه یک جزء جداگانه را دارد. حالت های صعب العبور (مانند حالت های بارگذاری) را می توان شبیه سازی کرد.

همراه با نمایش بصری حالت‌های مختلف و فهرستی از ویژگی‌ها، اغلب لازم است که یک توصیف کلی از محتوا بنویسید - منطق طراحی، موارد استفاده یا شرح نتایج آزمایش کاربر. یادگیری Markdown بسیار آسان است - در حالت ایده آل، دستورالعمل ها باید یک منبع مشترک برای طراحان و توسعه دهندگان باشد. Docz، Styleguidist، و Storybook راهی برای ترکیب آسان Markdown با مؤلفه ها ارائه می دهند.

Docz

در حال حاضر Docz فقط با React کار می کند، اما کار فعالی برای پشتیبانی از Preact، Vue و اجزای وب در حال انجام است. Docz جدیدترین ابزار از این سه ابزار است، اما توانسته است بیش از 14 ستاره در Github جمع آوری کند. 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 را ساده‌ترین روش برای درک و کار کردن با آن می‌دانم.

اگر از طرفداران مولد سایت استاتیک گتسبی هستید، 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 پشتیبانی می کند.

کتاب داستان

Storybook خود را به عنوان یک "محیط توسعه کامپوننت UI" معرفی می کند. به جای نوشتن اجزای نمونه در فایل های Markdown یا MDX، می نویسید داستان داخل فایل های جاوا اسکریپت داستان وضعیت خاص یک جزء را مستند کنید. به عنوان مثال، یک جزء ممکن است تاریخچه ای برای یک حالت بارگذاری شده و یک حالت غیرفعال داشته باشد (غیر فعال).

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

Storybook بسیار پیچیده تر از Styleguidist و Docz است. اما در عین حال، این محبوب ترین گزینه است؛ این پروژه بیش از 36 ستاره در Github دارد. این یک پروژه متن باز با 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é است. در صورت مشاهده هرگونه نادرستی یا پیشنهادی برای بهبود مقاله، در پیام شخصی برای من بنویسید.

منبع: www.habr.com