জীবনযাত্রার নির্দেশিকা - MDX এবং অন্যান্য কাঠামো

আপনার কাছে সর্বোত্তম ওপেন সোর্স প্রকল্প থাকতে পারে, তবে যদি এটির ভাল ডকুমেন্টেশন না থাকে, তবে এটি কখনই বন্ধ হবে না। অফিসে, ভাল ডকুমেন্টেশন আপনাকে একই প্রশ্নের উত্তর দিতে বাধা দেবে। ডকুমেন্টেশন এও নিশ্চিত করে যে মূল কর্মীরা কোম্পানি ছেড়ে চলে গেলে বা ভূমিকা পরিবর্তন করলে লোকেরা প্রকল্পটি বুঝতে পারে। জীবনযাত্রার নির্দেশিকা ডেটা অখণ্ডতা নিশ্চিত করতে সাহায্য করবে।

আপনার যদি দীর্ঘ পাঠ্য লিখতে হয়, মার্কডাউন HTML এর একটি দুর্দান্ত বিকল্প। কখনও কখনও মার্কডাউন সিনট্যাক্স যথেষ্ট নয়। এক্ষেত্রে আমরা এর ভিতরে HTML ব্যবহার করতে পারি। উদাহরণস্বরূপ, কাস্টম উপাদান। অতএব, আপনি যদি নেটিভ ওয়েব উপাদানগুলির সাথে একটি ডিজাইন সিস্টেম তৈরি করেন তবে সেগুলি সহজেই পাঠ্য ডকুমেন্টেশনে অন্তর্ভুক্ত করা যেতে পারে। আপনি যদি রিঅ্যাক্ট ব্যবহার করেন (বা অন্য কোন JSX ফ্রেমওয়ার্ক যেমন Preact বা Vue), আপনি MDX এর সাথে একই জিনিস করতে পারেন।

এই নিবন্ধটি ডকুমেন্টেশন লেখা এবং নির্দেশিকা তৈরির জন্য সরঞ্জামগুলির একটি বিস্তৃত ওভারভিউ। এখানে তালিকাভুক্ত সমস্ত সরঞ্জাম MDX ব্যবহার করে না, তবে এটি ক্রমবর্ধমানভাবে ডকুমেন্টেশন সরঞ্জামগুলিতে অন্তর্ভুক্ত করা হচ্ছে৷

MDX কি?

ফাইল .mdx মার্কডাউনের মতো একই সিনট্যাক্স রয়েছে, তবে আপনাকে ইন্টারেক্টিভ JSX উপাদানগুলি আমদানি করতে এবং আপনার সামগ্রীতে এম্বেড করতে দেয়। Vue উপাদানগুলির জন্য সমর্থন আলফাতে রয়েছে। MDX এর সাথে কাজ শুরু করতে, শুধু "Create React App" ইনস্টল করুন। Next.js এবং Gatsby এর জন্য প্লাগইন আছে। Docusaurus এর পরবর্তী সংস্করণ (সংস্করণ 2) এছাড়াও নেটিভ সমর্থন থাকবে।

ডকুসরাসের সাথে ডকুমেন্টেশন লেখা

ডকুসৌরাস ফেসবুকে লিখেছেন। তারা প্রতিক্রিয়া ছাড়া প্রতিটি ওপেন সোর্স প্রকল্পে এটি ব্যবহার করে। কোম্পানির বাইরে এটি Redux, Prettier, Gulp এবং Babel দ্বারা ব্যবহৃত হয়।

ডকুসারাস ব্যবহার করে এমন প্রকল্প।

Docusaurus লিখতে ব্যবহার করা যেতে পারে কোন ডকুমেন্টেশন, ফ্রন্টএন্ড বর্ণনা না শুধুমাত্র. এটির হুডের নিচে প্রতিক্রিয়া রয়েছে, তবে এটি ব্যবহার করার জন্য আপনাকে এটির সাথে পরিচিত হতে হবে না। এটি আপনার মার্কডাউন ফাইলগুলি নেয়, এক চিমটি জাদু এবং সুগঠিত, একটি সুন্দর নকশা সহ বিন্যাসিত এবং পাঠযোগ্য ডকুমেন্টেশন প্রস্তুত।

Redux ওয়েবসাইটে আপনি স্ট্যান্ডার্ড Docusaurus টেমপ্লেট দেখতে পারেন

Docusaurus দিয়ে নির্মিত ওয়েবসাইটগুলিতে একটি মার্কডাউন-ভিত্তিক ব্লগও অন্তর্ভুক্ত থাকতে পারে। সিনট্যাক্স হাইলাইট করার জন্য Prism.js অবিলম্বে সংযুক্ত। ডকুসারাস তুলনামূলকভাবে সম্প্রতি উপস্থিত হওয়া সত্ত্বেও, এটি স্ট্যাকশেয়ারে 2018 এর সেরা সরঞ্জাম হিসাবে স্বীকৃত হয়েছিল।

অন্যান্য বিষয়বস্তু তৈরির বিকল্প

ডকুসৌরাস বিশেষভাবে ডকুমেন্টেশন তৈরি করার জন্য ডিজাইন করা হয়েছে। অবশ্যই, একটি ওয়েবসাইট তৈরি করার জন্য এক মিলিয়ন এবং এক উপায় রয়েছে - আপনি যেকোনো ভাষায় আপনার নিজস্ব সমাধান স্থাপন করতে পারেন, CMS, বা একটি স্ট্যাটিক সাইট জেনারেটর ব্যবহার করতে পারেন।

উদাহরণস্বরূপ, প্রতিক্রিয়া, আইবিএম ডিজাইন সিস্টেম, অ্যাপোলো এবং ঘোস্ট সিএমএসের জন্য ডকুমেন্টেশন গ্যাটসবি ব্যবহার করে - একটি স্ট্যাটিক সাইট জেনারেটর যা প্রায়শই ব্লগের জন্য ব্যবহৃত হয়। আপনি যদি Vue এর সাথে কাজ করেন, তাহলে VuePres আপনার জন্য একটি ভাল বিকল্প। আরেকটি বিকল্প হল পাইথনে লেখা একটি জেনারেটর ব্যবহার করা - MkDocs। এটি ওপেন সোর্স এবং একটি একক YAML ফাইল ব্যবহার করে কনফিগার করা হয়েছে। গিটবুকও একটি ভাল বিকল্প, তবে এটি শুধুমাত্র পাবলিক এবং অ-বাণিজ্যিক দলের জন্য বিনামূল্যে। আপনি Git ব্যবহার করে সহজভাবে মার্ডাউন ফাইল আপলোড করতে পারেন এবং Github এ তাদের সাথে কাজ করতে পারেন।

ডকুমেন্টিং উপাদান: ডকজ, স্টোরিবুক এবং স্টাইলগাইডিস্ট

গাইডলাইন, সিস্টেম ডিজাইন, কম্পোনেন্ট লাইব্রেরি - আপনি এগুলোকে যে নামেই ডাকুন না কেন, ইদানীং এটি খুবই জনপ্রিয় হয়ে উঠেছে। 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>

আপনি আপনার নিজস্ব প্রতিক্রিয়া উপাদান সঙ্গে মোড়ানো করতে পারেন <Playground>অন্তর্নির্মিত কোডপেন বা কোডস্যান্ডবক্সের একটি অ্যানালগ তৈরি করতে - অর্থাৎ, আপনি আপনার উপাদান দেখতে পাবেন এবং এটি সম্পাদনা করতে পারেন।

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

<Props> একটি প্রদত্ত প্রতিক্রিয়া উপাদান, ডিফল্ট মান এবং সম্পত্তি প্রয়োজন কিনা এর জন্য সমস্ত উপলব্ধ বৈশিষ্ট্য দেখাবে।

<Props of={Button} />

ব্যক্তিগতভাবে, আমি এই MDX ভিত্তিক পদ্ধতিকে বোঝার জন্য সবচেয়ে সহজ এবং কাজ করার জন্য সবচেয়ে সহজ বলে মনে করি।

আপনি যদি Gatsby স্ট্যাটিক সাইট জেনারেটরের অনুরাগী হন, Docz একটি দুর্দান্ত ইন্টিগ্রেশন অফার করে৷

শৈলী গাইড

Docz-এর মতো, মার্কডাউন সিনট্যাক্স ব্যবহার করে উদাহরণ লেখা হয়। স্টাইলগুইডিস্ট নিয়মিত ফাইলগুলিতে মার্কডাউন কোড ব্লক (ট্রিপল কোট) ব্যবহার করে .md ফাইল, MDX নয়।

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

মার্কডাউনে কোড ব্লক সাধারণত শুধু কোড দেখায়। Styleguidist ব্যবহার করার সময়, একটি ভাষা ট্যাগ সহ কোডের যেকোনো ব্লক js, jsx বা javascript একটি প্রতিক্রিয়া উপাদান হিসাবে রেন্ডার হবে। Docz-এর মতো, কোডটি সম্পাদনাযোগ্য - আপনি বৈশিষ্ট্য পরিবর্তন করতে পারেন এবং অবিলম্বে ফলাফল দেখতে পারেন।

Styleguidist স্বয়ংক্রিয়ভাবে PropTypes, Flow বা Typescript ঘোষণা থেকে একটি সম্পত্তি টেবিল তৈরি করবে।

Styleguidist বর্তমানে React এবং Vue সমর্থন করে।

গল্পের বই

স্টোরিবুক নিজেকে একটি "UI উপাদান উন্নয়ন পরিবেশ" হিসাবে অবস্থান করে। মার্কডাউন বা MDX ফাইলের মধ্যে উদাহরণ উপাদান লেখার পরিবর্তে, আপনি লিখুন ইতিহাস জাভাস্ক্রিপ্ট ফাইলের ভিতরে। История একটি উপাদানের নির্দিষ্ট অবস্থা নথিভুক্ত করুন। উদাহরণস্বরূপ, একটি উপাদানের একটি লোড করা অবস্থা এবং একটি অক্ষম অবস্থার ইতিহাস থাকতে পারে (অক্ষম).

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>

স্টোরিবুকের নতুন বৈশিষ্ট্যগুলি পরের কয়েক মাসে ধীরে ধীরে রোল আউট হবে এবং দেখে মনে হচ্ছে এটি একটি বড় পদক্ষেপ হবে।

ফলাফল

একটি প্যাটার্ন লাইব্রেরির সুবিধাগুলি মিডিয়ামের লক্ষ লক্ষ নিবন্ধে প্রশংসিত হয়৷ ভালভাবে সম্পন্ন হলে, তারা সম্পর্কিত পণ্য তৈরি করা এবং পরিচয় বজায় রাখা সহজ করে তোলে। অবশ্যই, এই সরঞ্জামগুলির কোনটিই জাদুকরীভাবে একটি ডিজাইন সিস্টেম তৈরি করবে না। এর জন্য যত্নশীল ডিজাইন এবং CSS প্রয়োজন। কিন্তু যখন পুরো কোম্পানির কাছে একটি ডিজাইন সিস্টেম অ্যাক্সেসযোগ্য করার সময় আসে, তখন ডকজ, স্টোরিবুক এবং স্টাইলগুইডিস্ট দুর্দান্ত বিকল্প।

অনুবাদকের কাছ থেকে। হাব্রেতে এটি আমার প্রথম অভিজ্ঞতা। আপনি যদি কোন ভুলত্রুটি খুঁজে পান, বা নিবন্ধটি উন্নত করার জন্য পরামর্শ থাকলে, আমাকে একটি ব্যক্তিগত বার্তায় লিখুন।

উত্স: www.habr.com