لائیو رہنما خطوط - MDX اور دیگر فریم ورک

آپ کے پاس بہترین اوپن سورس پروجیکٹ ہو سکتا ہے، لیکن اگر اس میں اچھی دستاویزات نہیں ہیں، تو امکان ہے کہ یہ کبھی ختم نہیں ہو گا۔ دفتر میں، اچھی دستاویزات آپ کو انہی سوالات کے جوابات دینے سے روکیں گی۔ دستاویز اس بات کو بھی یقینی بناتی ہے کہ لوگ اس منصوبے کو سمجھ سکتے ہیں اگر اہم ملازمین کمپنی چھوڑ دیتے ہیں یا کردار بدل جاتے ہیں۔ زندہ رہنما خطوط ڈیٹا کی سالمیت کو یقینی بنانے میں مدد کریں گے۔

اگر آپ کو لمبا متن لکھنے کی ضرورت ہے تو مارک ڈاؤن HTML کا ایک بہترین متبادل ہے۔ بعض اوقات مارک ڈاؤن نحو کافی نہیں ہوتا ہے۔ اس صورت میں ہم اس کے اندر HTML استعمال کر سکتے ہیں۔ مثال کے طور پر، حسب ضرورت عناصر۔ لہذا، اگر آپ مقامی ویب اجزاء کے ساتھ ایک ڈیزائن سسٹم بنا رہے ہیں، تو انہیں متنی دستاویزات میں آسانی سے شامل کیا جا سکتا ہے۔ اگر آپ React (یا کوئی دوسرا JSX فریم ورک جیسے Preact یا Vue) استعمال کر رہے ہیں، تو آپ MDX کے ساتھ بھی ایسا ہی کر سکتے ہیں۔

یہ مضمون دستاویزات لکھنے اور رہنما خطوط بنانے کے لیے ٹولز کا ایک وسیع جائزہ ہے۔ یہاں درج تمام ٹولز MDX کا استعمال نہیں کرتے ہیں، لیکن یہ تیزی سے دستاویزی ٹولز میں شامل کیا جا رہا ہے۔

MDX کیا ہے؟

فائل .mdx مارک ڈاؤن جیسا ہی نحو ہے، لیکن آپ کو انٹرایکٹو JSX اجزاء درآمد کرنے اور انہیں اپنے مواد میں شامل کرنے کی اجازت دیتا ہے۔ Vue اجزاء کے لیے سپورٹ الفا میں ہے۔ MDX کے ساتھ کام شروع کرنے کے لیے، بس "Create React App" انسٹال کریں۔ Next.js اور Gatsby کے لیے پلگ ان موجود ہیں۔ Docusaurus کے اگلے ورژن (ورژن 2) کو بھی مقامی حمایت حاصل ہوگی۔

Docusaurus کے ساتھ دستاویزات لکھنا

Docusaurus نے فیس بک پر لکھا۔ وہ اسے ہر اوپن سورس پروجیکٹ پر استعمال کرتے ہیں سوائے React کے۔ کمپنی کے باہر اسے Redux، Prettier، Gulp اور Babel استعمال کرتے ہیں۔

پروجیکٹس جو Docusaurus استعمال کرتے ہیں۔

Docusaurus لکھنے کے لیے استعمال کیا جا سکتا ہے۔ کوئی بھی دستاویزات، نہ صرف فرنٹ اینڈ کو بیان کرنے کے لیے۔ اس میں ہڈ کے نیچے رد عمل ہے، لیکن اسے استعمال کرنے کے لیے آپ کو اس سے واقف ہونے کی ضرورت نہیں ہے۔ یہ آپ کی مارک ڈاؤن فائلوں کو لیتا ہے، ایک چٹکی بھر جادو اور اچھی طرح سے ساختہ، فارمیٹ شدہ اور پڑھنے کے قابل دستاویزات ایک خوبصورت ڈیزائن کے ساتھ تیار ہیں۔

Redux ویب سائٹ پر آپ معیاری Docusaurus ٹیمپلیٹ دیکھ سکتے ہیں۔

Docusaurus کے ساتھ بنی ویب سائٹس میں Markdown پر مبنی بلاگ بھی شامل ہو سکتا ہے۔ Prism.js نحو کو نمایاں کرنے کے لیے فوری طور پر منسلک ہے۔ اس حقیقت کے باوجود کہ Docusaurus نسبتاً حال ہی میں ظاہر ہوا، اسے StackShare پر 2018 کے بہترین ٹول کے طور پر تسلیم کیا گیا۔

دیگر مواد تخلیق کے اختیارات

Docusaurus خاص طور پر دستاویزات بنانے کے لیے ڈیزائن کیا گیا ہے۔ بلاشبہ، ویب سائٹ بنانے کے ایک ملین اور ایک طریقے ہیں - آپ کسی بھی زبان، CMS میں اپنا حل لگا سکتے ہیں، یا جامد سائٹ جنریٹر استعمال کر سکتے ہیں۔

مثال کے طور پر، React، IBM ڈیزائن سسٹم، Apollo اور Ghost CMS کے لیے دستاویزات گیٹسبی کا استعمال کرتی ہیں - ایک جامد سائٹ جنریٹر جو اکثر بلاگز کے لیے استعمال ہوتا ہے۔ اگر آپ Vue کے ساتھ کام کرتے ہیں، تو VuePress آپ کے لیے ایک اچھا آپشن ہے۔ دوسرا آپشن یہ ہے کہ Python - MkDocs میں لکھا ہوا جنریٹر استعمال کریں۔ یہ اوپن سورس ہے اور ایک واحد YAML فائل کا استعمال کرتے ہوئے ترتیب دیا گیا ہے۔ GitBook بھی ایک اچھا آپشن ہے، لیکن یہ صرف عوامی اور غیر تجارتی ٹیموں کے لیے مفت ہے۔ آپ گٹ کا استعمال کرتے ہوئے مارڈاؤن فائلوں کو آسانی سے اپ لوڈ بھی کر سکتے ہیں اور گیتھب میں ان کے ساتھ کام کر سکتے ہیں۔

دستاویزی اجزاء: ڈاکز، اسٹوری بک اور اسٹائل گائیڈسٹ

رہنما خطوط، نظام کا ڈیزائن، اجزاء کی لائبریریاں - آپ انہیں جو بھی کہتے ہیں، یہ حال ہی میں بہت مقبول ہوا ہے۔ React جیسے اجزاء کے فریم ورک کی آمد اور یہاں ذکر کردہ ٹولز نے انہیں وینٹی پروجیکٹس سے مفید ٹولز میں تبدیل کر دیا ہے۔

Storybook، Docz اور Style Guidist سبھی ایک ہی کام کرتے ہیں: انٹرایکٹو عناصر کو ڈسپلے کریں اور اپنے API کو دستاویز کریں۔ ایک پروجیکٹ میں درجنوں یا یہاں تک کہ سینکڑوں اجزاء ہوسکتے ہیں - سبھی مختلف ریاستوں اور طرزوں کے ساتھ۔ اگر آپ چاہتے ہیں کہ اجزاء دوبارہ استعمال کیے جائیں، تو لوگوں کو یہ جاننے کی ضرورت ہے کہ وہ موجود ہیں۔ ایسا کرنے کے لیے، صرف اجزاء کی فہرست بنائیں۔ رہنما خطوط آپ کے تمام اجزاء کا تلاش کرنے میں آسان جائزہ فراہم کرتے ہیں۔ یہ بصری مستقل مزاجی کو برقرار رکھنے اور بار بار کام سے بچنے میں مدد کرتا ہے۔

یہ ٹولز مختلف ریاستوں کو دیکھنے کا ایک آسان طریقہ فراہم کرتے ہیں۔ کسی جزو کی ہر حالت کو حقیقی اطلاق کے تناظر میں دوبارہ پیش کرنا مشکل ہوسکتا ہے۔ اصل ایپلیکیشن پر کلک کرنے کے بجائے، یہ ایک الگ جزو تیار کرنے کے قابل ہے۔ مشکل سے پہنچنے والی ریاستوں (جیسے لوڈنگ اسٹیٹس) کو نقل کیا جا سکتا ہے۔

مختلف ریاستوں کے بصری مظاہرے اور خصوصیات کی فہرست کے ساتھ، اکثر مواد کی عمومی وضاحت لکھنا ضروری ہوتا ہے - ڈیزائن کے استدلال، استعمال کے معاملات، یا صارف کی جانچ کے نتائج کی تفصیل۔ مارک ڈاؤن سیکھنا بہت آسان ہے - مثالی طور پر، رہنما خطوط ڈیزائنرز اور ڈویلپرز کے لیے مشترکہ وسیلہ ہونا چاہیے۔ ڈاکز، اسٹائل گائیڈسٹ، اور اسٹوری بک مارک ڈاؤن کو آسانی سے اجزاء کے ساتھ ملانے کا ایک طریقہ پیش کرتے ہیں۔

ڈاکز

فی الحال 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 کی طرح، کوڈ قابل تدوین ہے - آپ خصوصیات کو تبدیل کر سکتے ہیں اور فوری طور پر نتیجہ دیکھ سکتے ہیں۔

اسٹائل گائیڈسٹ خود بخود PropTypes، Flow یا Typescript ڈیکلریشنز سے پراپرٹی ٹیبل بنائے گا۔

اسٹائل گائیڈسٹ فی الحال React اور Vue کو سپورٹ کرتا ہے۔

اسٹوری بوک

سٹوری بک خود کو "UI جزو کی ترقی کے ماحول" کے طور پر رکھتی ہے۔ Markdown یا MDX فائلوں کے اندر مثال کے اجزاء لکھنے کے بجائے، آپ لکھتے ہیں۔ کہانیاں جاوا اسکرپٹ فائلوں کے اندر۔ کہانی کسی جزو کی مخصوص حالت کو دستاویز کریں۔ مثال کے طور پر، ایک جزو میں بھری ہوئی حالت اور ایک معذور حالت کی تاریخیں ہو سکتی ہیں (غیر فعال کر دیا).

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

اسٹوری بک اسٹائل گائیڈسٹ اور ڈاکز سے کہیں زیادہ پیچیدہ ہے۔ لیکن ایک ہی وقت میں، یہ سب سے زیادہ مقبول اختیار ہے؛ اس منصوبے میں Github پر 36،000 سے زیادہ ستارے ہیں. یہ ایک اوپن سورس پروجیکٹ ہے جس میں 657 شراکت دار اور کل وقتی عملہ ہے۔ اسے 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>

اسٹوری بک کی نئی خصوصیات اگلے چند مہینوں میں بتدریج سامنے آئیں گی اور ایسا لگتا ہے کہ یہ ایک بڑا قدم ہوگا۔

کے نتائج

ایک پیٹرن لائبریری کے فوائد میڈیم پر لاکھوں مضامین میں بیان کیے گئے ہیں۔ جب اچھی طرح سے کام کیا جاتا ہے، تو وہ متعلقہ مصنوعات بنانے اور شناخت کو برقرار رکھنے میں آسانی پیدا کرتے ہیں۔ بلاشبہ، ان میں سے کوئی بھی ٹول جادوئی طور پر ڈیزائن سسٹم نہیں بنائے گا۔ اس کے لیے محتاط ڈیزائن اور CSS کی ضرورت ہے۔ لیکن جب ڈیزائن سسٹم کو پوری کمپنی کے لیے قابل رسائی بنانے کا وقت آتا ہے، تو Docz، Storybook اور Style Guidist بہترین اختیارات ہیں۔

مترجم سے۔ Habré پر یہ میرا پہلا تجربہ ہے۔ اگر آپ کو کوئی غلطی نظر آتی ہے، یا مضمون کو بہتر بنانے کے لیے کوئی تجاویز ہیں، تو مجھے ذاتی پیغام میں لکھیں۔

ماخذ: www.habr.com