رهنما هدايتون - MDX ۽ ٻيا فريم ورڪ

توهان وٽ بهترين اوپن سورس پروجيڪٽ ٿي سگهي ٿو، پر جيڪڏهن ان وٽ سٺو دستاويز نه آهي، موقعا آهن ته اهو ڪڏهن به بند نه ٿيندو. آفيس ۾، سٺي دستاويز توهان کي ساڳئي سوالن جا جواب ڏيڻ کان روڪيندا. دستاويز پڻ يقيني بڻائي ٿو ته ماڻهو منصوبي کي سمجهي سگهن ٿا جيڪڏهن اهم ملازم ڪمپني ڇڏي وڃن يا ڪردار تبديل ڪن. رهنما هدايتون ڊيٽا جي سالميت کي يقيني بڻائڻ ۾ مدد ڪندي.

جيڪڏهن توهان کي ڊگهو متن لکڻ جي ضرورت آهي، مارڪ ڊائون HTML جو هڪ بهترين متبادل آهي. ڪڏهن ڪڏهن مارڪ ڊائون نحو ڪافي ناهي. ان صورت ۾ اسان ان جي اندر HTML استعمال ڪري سگهون ٿا. مثال طور، حسب ضرورت عناصر. تنهن ڪري، جيڪڏهن توهان هڪ ڊيزائن سسٽم ٺاهي رهيا آهيو مقامي ويب اجزاء سان، اهي آساني سان ٽيڪسٽ دستاويزن ۾ شامل ٿي سگهن ٿيون. جيڪڏھن توھان استعمال ڪري رھيا آھيو React (يا ڪو ٻيو JSX فريم ورڪ جھڙوڪ Preact يا Vue)، توھان MDX سان ساڳيو ڪم ڪري سگھو ٿا.

هي آرٽيڪل دستاويزن لکڻ ۽ هدايتون ٺاهڻ لاءِ اوزارن جو هڪ وسيع جائزو آهي. هتي درج ڪيل سڀئي اوزار MDX استعمال نٿا ڪن، پر اهو تيزيء سان دستاويزي اوزارن ۾ شامل ڪيو پيو وڃي.

MDX ڇا آهي؟

فائيل .mdx ساڳيو نحو آهي Markdown جهڙو، پر توهان کي اجازت ڏئي ٿو ته انٽرايڪٽو JSX اجزاء درآمد ڪري ۽ انهن کي توهان جي مواد ۾ شامل ڪري. Vue اجزاء لاءِ سپورٽ الفا ۾ آهي. MDX سان ڪم ڪرڻ شروع ڪرڻ لاءِ، بس انسٽال ڪريو “Create React App”. Next.js ۽ Gatsby لاءِ پلگ ان آهن. Docusaurus جي ايندڙ ورزن (ورجن 2) کي به مقامي سپورٽ حاصل هوندي.

Docusaurus سان دستاويز لکڻ

Docusaurus Facebook تي لکيو. اهي ان کي هر اوپن سورس پروجيڪٽ تي استعمال ڪندا آهن سواءِ رد عمل جي. ڪمپني کان ٻاهر اهو استعمال ڪيو ويندو آهي ريڊڪس، پريٽير، گلپ ۽ بابل.

منصوبا جيڪي Docusaurus استعمال ڪن ٿا.

Docusaurus لکڻ لاء استعمال ڪري سگهجي ٿو ڪوبہ دستاويز، نه صرف فرنٽ اينڊ بيان ڪرڻ لاءِ. اهو هود جي تحت رد عمل آهي، پر توهان کي ان کي استعمال ڪرڻ لاء ان سان واقف ٿيڻ جي ضرورت ناهي. اهو توهان جي مارڪ ڊائون فائلن کي وٺي ٿو، جادو جي هڪ چيٽ ۽ چڱي طرح ٺهيل، فارميٽ ٿيل ۽ پڙهڻ جي قابل دستاويز هڪ خوبصورت ڊيزائن سان تيار آهي.

Redux ويب سائيٽ تي توهان معياري Docusaurus ٽيمپليٽ ڏسي سگهو ٿا

Docusaurus سان ٺهيل ويب سائيٽون پڻ شامل ڪري سگھن ٿيون مارڪ ڊائون تي ٻڌل بلاگ. Prism.js نحو نمايان ڪرڻ لاء فوري طور تي ڳنڍيل آهي. ان حقيقت جي باوجود ته Docusaurus نسبتا تازو ظاهر ٿيو، ان کي 2018 جو بهترين اوزار طور سڃاتو ويو StackShare.

ٻيا مواد ٺاهڻ جا اختيار

Docusaurus خاص طور تي دستاويز ٺاهڻ لاء ٺهيل آهي. يقينن، ويب سائيٽ ٺاهڻ لاءِ هڪ لک ۽ هڪ طريقا آهن - توهان ڪنهن به ٻولي، CMS ۾ پنهنجو حل ترتيب ڏئي سگهو ٿا، يا هڪ مستحڪم سائيٽ جنريٽر استعمال ڪري سگهو ٿا.

مثال طور، React لاءِ دستاويز، IBM ڊيزائن سسٽم، اپولو ۽ Ghost CMS استعمال ڪندا آهن گيٽسبي - هڪ جامد سائيٽ جنريٽر جيڪو اڪثر بلاگن لاءِ استعمال ٿيندو آهي. جيڪڏهن توهان Vue سان ڪم ڪريو ٿا، پوء VuePress توهان لاء سٺو اختيار آهي. ٻيو اختيار استعمال ڪرڻ آهي هڪ جنريٽر پٿون ۾ لکيل آهي - MkDocs. اهو کليل ذريعو آهي ۽ هڪ واحد YAML فائل استعمال ڪندي ترتيب ڏنل آهي. GitBook پڻ هڪ سٺو اختيار آهي، پر اهو صرف عوامي ۽ غير تجارتي ٽيمن لاءِ مفت آهي. توهان پڻ Git استعمال ڪندي مارڊون فائلون اپلوڊ ڪري سگهو ٿا ۽ Github ۾ انهن سان ڪم ڪري سگهو ٿا.

دستاويزي اجزاء: Docz، Storybook ۽ Style Guidist

ھدايتون، سسٽم ڊيزائن، جزو لائبريريون - جيڪي توھان انھن کي سڏيندا آھيو، اھو تازو مقبول ٿي چڪو آھي. اجزاء جي فريم ورڪ جي آمد جهڙوڪ React ۽ هتي ذڪر ڪيل اوزار انهن کي وينٽي پروجيڪٽ کان مفيد اوزار ۾ تبديل ڪري ڇڏيو آهي.

Storybook، Docz ۽ Style Guidist سڀ ساڳيو ڪم ڪن ٿا: انٽرايڪٽو عناصر ڏيکاريو ۽ سندن API دستاويز ڪريو. هڪ پروجيڪٽ ۾ درجن يا ان کان به سوين جزا هوندا - سڀ مختلف رياستن ۽ اندازن سان. جيڪڏهن توهان چاهيو ٿا ته اجزاء ٻيهر استعمال ڪيا وڃن، ماڻهن کي ڄاڻڻ جي ضرورت آهي ته اهي موجود آهن. هن کي ڪرڻ لاء، صرف اجزاء کي ترتيب ڏيو. ھدايتون مهيا ڪن ٿيون ھڪڙي آسان ڳولڻ لاءِ توھان جي سڀني حصن جو جائزو. هي بصري استحڪام کي برقرار رکڻ ۽ بار بار ڪم کان بچڻ ۾ مدد ڪري ٿو.

اهي اوزار مختلف رياستن کي ڏسڻ لاءِ آسان رستو مهيا ڪن ٿا. اهو ڏکيو ٿي سگهي ٿو ته هڪ جزو جي هر رياست کي حقيقي ايپليڪيشن جي حوالي سان ٻيهر پيدا ڪرڻ. اصل ايپليڪيشن تي ڪلڪ ڪرڻ جي بدران، اهو هڪ الڳ جزو ٺاهڻ جي قابل آهي. سخت-پھچندڙ رياستون (جهڙوڪ لوڊ ڪرڻ واريون رياستون) ٺاھي سگھجن ٿيون.

مختلف رياستن جي بصري مظاهري سان گڏ ۽ ملڪيت جي هڪ فهرست، اهو اڪثر ڪري ضروري آهي ته مواد جي هڪ عام وضاحت لکڻ لاء - ڊيزائن جي منطق، استعمال جا ڪيس، يا صارف جي جانچ جي نتيجن جي وضاحت. Markdown سکڻ لاءِ تمام آسان آهي - مثالي طور تي، رهنمائي ڪرڻ گهرجي هڪ گڏيل وسيلو هجڻ گهرجي ڊزائنر ۽ ڊولپرز لاءِ. Docz, Style Guidist, and Storybook هڪ طريقو پيش ڪن ٿا آساني سان مارڪ ڊائون کي اجزاء سان ملايو.

ڊڪز

في الحال 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>

توھان پنھنجي پنھنجي رد عمل جي اجزاء سان لپي سگھو ٿا <Playground>بلٽ ان CodePen يا CodeSandbox جو هڪ اينالاگ ٺاهڻ لاءِ - يعني توهان پنهنجو حصو ڏسو ۽ ان کي ايڊٽ ڪري سگهو ٿا.

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

<Props> ڏيکاريندو سڀني موجود ملڪيتن لاءِ ڏنل React جزو، ڊفالٽ قدر، ۽ ڇا ملڪيت گھربل آھي.

<Props of={Button} />

ذاتي طور تي، مون کي هن MDX تي ٻڌل طريقي سان سمجھڻ ۾ آسان ۽ ڪم ڪرڻ لاء تمام آسان آهي.

جيڪڏهن توهان گيٽسبي جامد سائيٽ جنريٽر جا پرستار آهيو، Docz هڪ بهترين انضمام پيش ڪري ٿو.

انداز ھدايت

Docz وانگر، مثال لکيا ويا آهن مارڪ ڊائون نحو استعمال ڪندي. اسٽائل گائيڊسٽ استعمال ڪري ٿو مارڪ ڊائون ڪوڊ بلاڪ (ٽرپل ڪوٽس) باقاعده فائلن ۾ .md فائلون، نه MDX.

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

مارڪ ڊائون ۾ ڪوڊ بلاڪ عام طور تي صرف ڪوڊ ڏيکاريو. جڏهن استعمال ڪندي Styleguidist، ڪوڊ جو ڪو به بلاڪ هڪ ٻولي ٽيگ سان js, jsx يا javascript هڪ React جزو طور پيش ڪندو. Docz وانگر، ڪوڊ قابل تدوين آهي - توهان ملڪيت تبديل ڪري سگهو ٿا ۽ فوري طور نتيجو ڏسي سگهو ٿا.

اسٽائل گائيڊسٽ خود بخود پروپي ٽائپس، فلو يا ٽائپ اسڪرپٽ بيانن مان هڪ ملڪيت جدول ٺاهيندو.

اسٽائل گائيڊسٽ في الحال رد عمل ۽ وييو کي سپورٽ ڪري ٿو.

ڪهاڻي ڪتاب

ڪهاڻي ڪتاب پاڻ کي "UI جزو جي ترقي واري ماحول" جي حيثيت رکي ٿو. مارڪ ڊائونڊ يا ايم ڊي ايڪس فائلن اندر مثال جا حصا لکڻ جي بدران، توهان لکندا آهيو تاريخ Javascript فائلن جي اندر. История هڪ جزو جي مخصوص حالت کي دستاويز ڪريو. مثال طور، هڪ جزو شايد لوڊ ٿيل رياست ۽ معذور رياست لاءِ تاريخون هجن (معذور).

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

ڪهاڻي ڪتاب اسٽائل گائيڊسٽ ۽ ڊڪز کان وڌيڪ پيچيده آهي. پر ساڳئي وقت، هي سڀ کان وڌيڪ مشهور اختيار آهي؛ پروجيڪٽ 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 جون نيون خاصيتون ايندڙ ڪجهه مهينن ۾ بتدريج ختم ٿينديون ۽ اهو لڳي ٿو ته اهو هڪ وڏو قدم هوندو.

نتيجو

ھڪڙي نموني لائبريري جا فائدا ميڊيم تي لکين مضمونن ۾ بيان ڪيا ويا آھن. جڏهن سٺو ٿي چڪو آهي، اهي لاڳاپيل مصنوعات ٺاهڻ ۽ سڃاڻپ برقرار رکڻ آسان بڻائي ٿي. يقينن، انهن اوزارن مان ڪو به جادوگر هڪ ڊزائين سسٽم ٺاهي سگهندو. اهو محتاط ڊيزائن ۽ CSS جي ضرورت آهي. پر جڏهن اهو وقت اچي ٿو هڪ ڊيزائن سسٽم کي پوري ڪمپني تائين پهچ، Docz، Storybook ۽ Style Guidist بهترين اختيار آهن.

مترجم کان. هي منهنجو پهريون تجربو آهي Habré تي. جيڪڏھن توھان ڪي غلطيون ڳوليندا آھيو، يا مضمون کي بھتر ڪرڻ لاءِ تجويزون آھن، مون کي ذاتي پيغام ۾ لکو.

جو ذريعو: www.habr.com