د ژوند کولو لارښوونې - MDX او نور چوکاټونه

تاسو کولی شئ د خلاصې سرچینې غوره پروژه ولرئ، مګر که دا ښه اسناد ونه لري، امکانات دا دي چې دا به هیڅکله پای ته ونه رسیږي. په دفتر کې، ښه اسناد به تاسو ته د ورته پوښتنو ځواب ورکولو مخه ونیسي. اسناد دا هم ډاډه کوي چې خلک کولی شي په پروژه پوه شي که کلیدي کارمندان شرکت پریږدي یا رولونه بدل شي. د ژوند کولو لارښوونې به د معلوماتو بشپړتیا ډاډمن کولو کې مرسته وکړي.

که تاسو اوږد متن لیکلو ته اړتیا لرئ، مارک ډاون د HTML لپاره غوره بدیل دی. ځینې ​​​​وختونه د مارک ډاون ترکیب کافي ندي. پدې حالت کې موږ کولی شو د هغې دننه HTML وکاروو. د مثال په توګه، دودیز عناصر. له همدې امله، که تاسو د اصلي ویب اجزاوو سره د ډیزاین سیسټم جوړ کړئ، دوی په اسانۍ سره د متن اسنادو کې شامل کیدی شي. که تاسو د عکس العمل (یا کوم بل JSX چوکاټ لکه Preact یا Vue) کاروئ، تاسو د MDX سره ورته کار کولی شئ.

دا مقاله د اسنادو لیکلو او لارښودونو رامینځته کولو لپاره د وسیلو پراخه کتنه ده. دلته لیست شوي ټول وسایل MDX نه کاروي، مګر دا په زیاتیدونکي توګه د اسنادو په وسیلو کې شاملیږي.

MDX څه شی دی؟

د دوتنې .mdx د مارک ډاون په څیر ورته ترکیب لري، مګر تاسو ته اجازه درکوي چې د متقابل JSX اجزا وارد کړئ او ستاسو مینځپانګې کې یې ځای په ځای کړئ. د Vue برخو لپاره ملاتړ په الفا کې دی. د MDX سره کار پیل کولو لپاره ، یوازې "د عکس العمل ایپ رامینځته کړئ" نصب کړئ. د Next.js او Gatsby لپاره پلگ انونه شتون لري. د Docusaurus راتلونکی نسخه (نسخه 2) به هم اصلي ملاتړ ولري.

د Docusaurus سره د اسنادو لیکل

Docusaurus په فیسبوک کې لیکلي. دوی دا د عکس العمل پرته په هرې خلاصې سرچینې پروژه کې کاروي. د شرکت څخه بهر دا د Redux، Prettier، Gulp او Babel لخوا کارول کیږي.

هغه پروژې چې د Docusaurus کاروي.

Docusaurus د لیکلو لپاره کارول کیدی شي هر اسناد، نه یوازې د مخکینۍ برخې تشریح کولو لپاره. دا د هود لاندې عکس العمل لري ، مګر تاسو اړتیا نلرئ د دې کارولو لپاره ورسره آشنا اوسئ. دا ستاسو د مارک ډاون فایلونه اخلي، یو چټک جادو او ښه جوړ شوی، بڼه شوي او د لوستلو وړ اسناد د ښکلي ډیزاین سره چمتو دي.

په ریډکس ویب پاڼه کې تاسو کولی شئ د معیاري Docusaurus ټیمپلیټ وګورئ

د Docusaurus سره جوړ شوي ویب پاڼې کولی شي د مارک ډاون پر بنسټ بلاګ هم شامل کړي. Prism.js سمدلاسه د نحو روښانه کولو لپاره وصل دی. د دې حقیقت سره سره چې Docusaurus نسبتا پدې وروستیو کې راڅرګند شو، دا په StackShare کې د 2018 غوره وسیله په توګه پیژندل شوی.

د منځپانګې جوړولو نور اختیارونه

Docusaurus په ځانګړې توګه د اسنادو جوړولو لپاره ډیزاین شوی. البته، د ویب پاڼې جوړولو لپاره یو ملیون او یوې لارې شتون لري - تاسو کولی شئ خپل حل په هره ژبه، CMS کې ځای پر ځای کړئ، یا د جامد سایټ جنریټر وکاروئ.

د مثال په توګه، د عکس العمل لپاره اسناد، د IBM ډیزاین سیسټم، اپولو او Ghost CMS د ګیټسبی څخه کار اخلي - یو جامد سایټ جنراتور چې ډیری وختونه د بلاګونو لپاره کارول کیږي. که تاسو د Vue سره کار کوئ، نو VuePress ستاسو لپاره یو ښه اختیار دی. بل اختیار دا دی چې په Python - MkDocs کې لیکل شوي جنریټر وکاروئ. دا خلاص سرچینه ده او د یو واحد YAML فایل په کارولو سره تنظیم شوی. GitBook هم یو ښه انتخاب دی، مګر دا یوازې د عامه او غیر سوداګریزو ټیمونو لپاره وړیا دی. تاسو کولی شئ په ساده ډول د Git په کارولو سره د مارډون فایلونه اپلوډ کړئ او په ګیتوب کې ورسره کار وکړئ.

د مستند کولو برخې: Docz، د کیسې کتاب او سټایل لارښود

لارښوونې، د سیسټم ډیزاین، اجزاو کتابتونونه - هر هغه څه چې تاسو یې ورته وایئ، دا پدې وروستیو کې خورا مشهور شوي. د اجزاو چوکاټونو راتلل لکه عکس العمل او دلته ذکر شوي وسیلې دوی د باطلو پروژو څخه په ګټورو وسیلو بدل کړي.

Storybook، Docz او Style Guidist ټول ورته کار کوي: متقابل عناصر ښکاره کړئ او د دوی API مستند کړئ. یوه پروژه کولی شي لسګونه یا حتی په سلګونو برخې ولري - ټول د مختلف ریاستونو او سټایلونو سره. که تاسو غواړئ اجزا بیا وکارول شي، خلک باید پوه شي چې دوی شتون لري. د دې کولو لپاره، په ساده ډول د اجزاوو لیست کول. لارښوونې ستاسو د ټولو برخو د موندلو لپاره اسانه کتنه وړاندې کوي. دا د لید ثبات ساتلو کې مرسته کوي او د تکرار کار څخه مخنیوی کوي.

دا وسیلې د مختلف ایالتونو لیدو لپاره اسانه لار چمتو کوي. د ریښتیني غوښتنلیک په شرایطو کې د یوې برخې هر حالت بیا تولید کول ستونزمن کیدی شي. په ریښتیني غوښتنلیک باندې کلیک کولو پرځای ، دا د جلا برخې رامینځته کولو ارزښت لري. د لاسرسي سخت حالتونه (لکه د بارولو ریاستونه) سمولیټ کیدی شي.

د مختلفو ایالتونو د بصری مظاهرې او د ملکیتونو لیست سره، دا ډیری وختونه اړین دي چې د منځپانګې عمومي توضیحات ولیکئ - د ډیزاین دلیلونه، د کارولو قضیې، یا د کاروونکي ازموینې پایلو توضیحات. Markdown زده کول خورا اسانه دي - په مثالي توګه، لارښوونې باید د ډیزاینرانو او پراختیا کونکو لپاره شریکه سرچینه وي. Docz، Style Guidist، او Storybook د اجزاو سره د مارک ډاون په اسانۍ سره مخلوط کولو لپاره یوه لاره وړاندې کوي.

Docz

اوس مهال Docz یوازې د React سره کار کوي، مګر د Preact، Vue او ویب اجزاو مالتړ لپاره فعال کار روان دی. Docz د دریو وسیلو څخه خورا وروستي دی ، مګر دا په ګیتوب کې له 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>

تاسو کولی شئ خپل د عکس العمل اجزاو سره وتړئ <Playground>د جوړ شوي CodePen یا CodeSandbox یو انلاګ رامینځته کولو لپاره - دا دی چې تاسو خپله برخه وګورئ او ترمیم کولی شئ.

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

<Props> د ورکړل شوي عکس العمل برخې لپاره به ټول موجود ملکیتونه وښیې ، ډیفالټ ارزښتونه ، او ایا ملکیت اړین دی.

<Props of={Button} />

په شخصي توګه، زه د MDX پر بنسټ دا طریقه د پوهیدو لپاره ترټولو اسانه او د کار کولو لپاره ترټولو اسانه وموم.

که تاسو د ګیټسبي جامد سایټ جنراتور پرستار یاست، Docz یو ښه ادغام وړاندیز کوي.

د سټایل لارښود

د Docz په څیر، مثالونه د مارک ډاون نحو په کارولو سره لیکل شوي. سټایل ګایډیسټ په منظم فایلونو کې د مارک ډاون کوډ بلاکونه (درې ځله نرخونه) کاروي .md فایلونه، نه MDX.

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

په مارک ډاون کې د کوډ بلاکونه معمولا یوازې کوډ ښیې. کله چې سټایل ګایډیسټ کاروئ ، د ژبې ټګ سره د کوډ کوم بلاک js, jsx او یا javascript د عکس العمل برخې په توګه به وړاندې شي. د Docz په څیر، کوډ د ترمیم وړ دی - تاسو کولی شئ ملکیتونه بدل کړئ او سمدستي پایله وګورئ.

سټایل ګایډیسټ به په اوتومات ډول د پروپ ټایپس ، فلو یا ټایپ سکریپټ اعلامیو څخه د ملکیت جدول رامینځته کړي.

سټایل ګایډیسټ اوس مهال د عکس العمل او ویو ملاتړ کوي.

د کيسې کتاب

د کیسې کتاب ځان د "UI برخې پراختیا چاپیریال" په توګه موقعیت لري. د مارک ډاون یا MDX فایلونو دننه د مثال اجزا لیکلو پرځای ، تاسو ولیکئ تاریخ د Javascript فایلونو دننه. История د یوې برخې ځانګړي حالت مستند کړئ. د مثال په توګه، یوه برخه ممکن د بار شوي حالت او معلول حالت لپاره تاریخ ولري (معیوب).

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

د کیسې کتاب د سټایل ګایډیسټ او ډاکز په پرتله خورا پیچلی دی. مګر په ورته وخت کې، دا خورا مشهور انتخاب دی؛ پروژه په ګیتوب کې له 36 څخه ډیر ستوري لري. دا د خلاصې سرچینې پروژه ده چې 000 مرسته کونکي او بشپړ وخت کارمندان لري. دا د Airbnb، Algolia، Atlassian، Lyft او Salesforce لخوا کارول کیږي. د کیسې کتاب د سیالانو په پرتله د ډیرو چوکاټونو ملاتړ کوي - عکس العمل ، عکس العمل اصلي ، ویو ، زاویه ، میتریل ، امبر ، فساد ، سویلټ او منظم HTML.

په راتلونکي خپرونه کې به د Docz او MDX څخه ځانګړتیاوې وي.

# Button

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

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

د کیسې بوک نوې ب featuresې به په تدریجي ډول په راتلونکو څو میاشتو کې راپورته شي او داسې ښکاري چې دا به یو لوی ګام وي.

پایلې

د نمونې کتابتون ګټې په میډیم کې په ملیونونو مقالو کې تعریف شوي. کله چې ښه ترسره شي، دوی د اړونده محصولاتو رامینځته کول او د هویت ساتل اسانه کوي. البته، د دې وسیلو څخه هیڅ یو به په جادویی ډول د ډیزاین سیسټم رامینځته نکړي. دا محتاط ډیزاین او CSS ته اړتیا لري. مګر کله چې دا د ډیزاین سیسټم رامینځته کولو وخت راځي چې ټول شرکت ته د لاسرسي وړ وي ، Docz ، Storybook او Style Guidist عالي اختیارونه دي.

د ژباړونکي څخه. دا په هابري کې زما لومړۍ تجربه ده. که تاسو کومه نیمګړتیا ومومئ، یا د مقالې د ښه کولو لپاره وړاندیزونه لرئ، ما ته په شخصي پیغام کې ولیکئ.

سرچینه: www.habr.com