जीवन निर्देशनहरू - MDX र अन्य फ्रेमवर्कहरू

तपाईंसँग राम्रो खुला स्रोत परियोजना हुन सक्छ, तर यदि यसमा राम्रो कागजात छैन भने, सम्भावनाहरू यो कहिल्यै बन्द हुनेछैन। अफिसमा, राम्रो कागजातले तपाईंलाई एउटै प्रश्नहरूको बारम्बार जवाफ दिनबाट जोगाउँछ। कागजातले यो पनि सुनिश्चित गर्दछ कि यदि प्रमुख कर्मचारीहरूले कम्पनी छोड्छन् वा भूमिका परिवर्तन गर्छन् भने मानिसहरूले परियोजनाको अर्थ बुझाउन सक्छन्। प्रत्यक्ष दिशानिर्देशहरूले डेटा अखण्डता सुनिश्चित गर्न मद्दत गर्दछ।

यदि तपाईंलाई लामो पाठ लेख्न आवश्यक छ भने, मार्कडाउन HTML को लागि एक उत्कृष्ट विकल्प हो। कहिलेकाहीँ मार्कडाउन सिन्ट्याक्स पर्याप्त हुँदैन। यस अवस्थामा, हामी यसको भित्र HTML प्रयोग गर्न सक्छौं। उदाहरणका लागि, अनुकूलन तत्वहरू। त्यसकारण, यदि तपाइँ नेटिभ वेब कम्पोनेन्टहरूसँग डिजाइन प्रणाली निर्माण गर्दै हुनुहुन्छ भने, तिनीहरूलाई पाठ कागजातमा समावेश गर्न सजिलो छ। यदि तपाइँ React (वा Preact वा Vue जस्तै कुनै अन्य JSX फ्रेमवर्क) प्रयोग गर्दै हुनुहुन्छ भने, तपाइँ MDX को साथ पनि गर्न सक्नुहुन्छ।

यो लेख कागजात लेख्न र एक दिशानिर्देश सिर्जना गर्न उपकरणहरूको एक विस्तृत सिंहावलोकन हो। यहाँ सूचीबद्ध गरिएका सबै उपकरणहरूले MDX प्रयोग गर्दैनन्, तर यो बढ्दो रूपमा कागजात उपकरणहरूमा समावेश भइरहेको छ।

MDX भनेको के हो?

फाइल .mdx मार्कडाउन जस्तै समान वाक्य रचना छ तर तपाईंलाई अन्तरक्रियात्मक JSX कम्पोनेन्टहरू आयात गर्न र तिनीहरूलाई तपाईंको सामग्रीमा इम्बेड गर्न अनुमति दिन्छ। Vue कम्पोनेन्टहरूको लागि समर्थन अल्फामा छ। MDX सँग काम सुरु गर्नको लागि, केवल "Create React App" स्थापना गर्नुहोस्। Next.js र Gatsby का लागि प्लगइनहरू छन्। Docusaurus को अर्को संस्करण (संस्करण 2) मा पनि निर्मित समर्थन हुनेछ।

Docusaurus संग कागजात लेखन

Docusaurus फेसबुकमा लेखे। तिनीहरूले यसलाई प्रतिक्रिया बाहेक हरेक खुला स्रोत परियोजनामा ​​प्रयोग गर्छन्। कम्पनी बाहिर, Redux, Prettier, Gulp, र Babel ले यसलाई प्रयोग गर्दछ।

Docusaurus प्रयोग गर्ने परियोजनाहरू।

Docusaurus लेख्न प्रयोग गर्न सकिन्छ कुनै पनि कागजात, फ्रन्टएन्ड वर्णन गर्नको लागि मात्र होइन। यसमा हुड मुनि प्रतिक्रिया छ, तर तपाईं यसलाई प्रयोग गर्न परिचित हुनु पर्दैन। यसले तपाईंको मार्कडाउन फाइलहरू लिन्छ, एक चुटकी जादू र राम्रोसँग संरचित, ढाँचाबद्ध र पढ्न योग्य कागजातहरू सुन्दर डिजाइनको साथ तयार छ।

तपाईंले Redux वेबसाइटमा पूर्वनिर्धारित Docusaurus टेम्प्लेट हेर्न सक्नुहुन्छ।

Docusaurus सँग बनाइएको साइटहरूले मार्कडाउन-आधारित ब्लग पनि समावेश गर्न सक्छ। सिन्ट्याक्स हाइलाइटिङको लागि, Prism.js तुरुन्तै समावेश गरिएको छ। Docusaurus अपेक्षाकृत हालै देखा परेको तथ्यको बावजुद, यसलाई StackShare मा 2018 को उत्कृष्ट उपकरणको रूपमा मान्यता प्राप्त भयो।

अन्य सामग्री निर्माण विकल्पहरू

Docusaurus विशेष गरी कागजातहरू सिर्जना गर्न डिजाइन गरिएको हो। निस्सन्देह, त्यहाँ वेबसाइट बनाउन लाखौं र एक तरिकाहरू छन् - तपाईं कुनै पनि भाषा, CMS, वा एक स्थिर साइट जनरेटर प्रयोग गर्न आफ्नो समाधान तैनाती गर्न सक्नुहुन्छ।

उदाहरण को लागी, प्रतिक्रिया को लागी कागजात, IBM डिजाइन प्रणाली, Apollo, र Ghost CMS ले ग्याट्सबी प्रयोग गर्दछ, एक स्थिर साइट जेनेरेटर अक्सर ब्लगहरु को लागी प्रयोग गरिन्छ। यदि तपाइँ Vue सँग काम गर्दै हुनुहुन्छ भने VuePress तपाइँको लागि राम्रो विकल्प हो। अर्को विकल्प पाइथन - MkDocs मा लेखिएको जनरेटर प्रयोग गर्न हो। यो एकल YAML फाइलसँग खुला र कन्फिगर गरिएको छ। GitBook पनि एक राम्रो विकल्प हो, तर यो खुला र गैर-व्यावसायिक टोलीहरूको लागि मात्र निःशुल्क छ। तपाईं केवल git प्रयोग गरेर mardown फाइलहरू अपलोड गर्न सक्नुहुन्छ र Github मा तिनीहरूसँग काम गर्न सक्नुहुन्छ।

कम्पोनेन्ट दस्तावेजीकरण: Docz, Storybook र Styleguidist

दिशानिर्देशहरू, प्रणाली डिजाइन, कम्पोनेन्ट पुस्तकालयहरू, जुन तपाईं तिनीहरूलाई कल गर्न चाहनुहुन्छ, यी हालै धेरै लोकप्रिय भएका छन्। प्रतिक्रिया र यहाँ उल्लेख गरिएका उपकरणहरू जस्ता कम्पोनेन्ट फ्रेमवर्कहरूको उदयले भ्यानिटी प्रोजेक्टहरूबाट उपयोगी उपकरणहरूमा रूपान्तरण गर्न सम्भव बनाएको छ।

Storybook, Docz र Styleguidist ले एउटै काम गर्छ: अन्तरक्रियात्मक तत्वहरू प्रदर्शन गर्नुहोस् र तिनीहरूको API कागजात गर्नुहोस्। एक परियोजनामा ​​दर्जनौं वा सयौं कम्पोनेन्टहरू हुन सक्छन्, सबै बिभिन्न राज्यहरू र शैलीहरूसँग। यदि तपाइँ घटकहरू पुन: प्रयोग गर्न चाहनुहुन्छ भने, मानिसहरूलाई थाहा छ कि तिनीहरू अवस्थित छन्। यो गर्न, यो घटक सूची गर्न पर्याप्त छ। दिशानिर्देशहरूले तपाइँका सबै घटकहरूको खोजी गर्न सजिलो सिंहावलोकन प्रदान गर्दछ। यसले दृश्य स्थिरता कायम राख्न र दोहोरिने कामबाट बच्न मद्दत गर्दछ।

यी उपकरणहरूले विभिन्न राज्यहरू हेर्नको लागि सुविधाजनक तरिका प्रदान गर्दछ। वास्तविक अनुप्रयोगको सन्दर्भमा कम्पोनेन्टको प्रत्येक अवस्थालाई नक्कल गर्न गाह्रो हुन सक्छ। वास्तविक अनुप्रयोगमा क्लिक गर्नुको सट्टा, यो एक अलग घटक विकास गर्न लायक छ। हार्ड-टु-पहुँच अवस्थाहरू मोडेल गर्न सम्भव छ (उदाहरणका लागि, लोडिङ अवस्था)।

विभिन्न राज्यहरूको दृश्य प्रदर्शन र गुणहरूको सूचीको साथमा, यो प्राय: सामग्रीको सामान्य विवरण लेख्न आवश्यक छ - डिजाइन तर्कहरू, प्रयोग केसहरू, वा प्रयोगकर्ता परीक्षणको नतिजाहरूको विवरण। मार्कडाउन सिक्न धेरै सजिलो छ - आदर्श रूपमा, दिशानिर्देशहरू डिजाइनर र विकासकर्ताहरूको लागि साझा स्रोत हुनुपर्छ। Docz, Styleguidist, र Storybook ले मार्कडाउनलाई कम्पोनेन्टहरूसँग सजिलैसँग मिलाउने तरिका प्रस्ताव गर्दछ।

कागजात

हाल, Docz ले प्रतिक्रियासँग मात्र काम गर्दछ, तर सक्रिय रूपमा 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> दिइएको प्रतिक्रिया कम्पोनेन्ट, पूर्वनिर्धारित मानहरू र गुण आवश्यक छ कि छैनका लागि सबै उपलब्ध गुणहरू देखाउनेछ।

<Props of={Button} />

व्यक्तिगत रूपमा, मैले यो MDX-आधारित दृष्टिकोणलाई बुझ्नको लागि सबैभन्दा सजिलो र काम गर्न सबैभन्दा सजिलो पाउँछु।

यदि तपाईं ग्याट्सबीको स्थिर साइट जनरेटरको प्रशंसक हुनुहुन्छ भने, 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>
  ))

Storybook Styleguidist र Docz भन्दा धेरै जटिल छ। तर एकै समयमा, यो सबैभन्दा लोकप्रिय विकल्प हो, Github मा परियोजना 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 डिजाइन आवश्यक छ। तर जब यो सम्पूर्ण कम्पनीलाई डिजाइन प्रणाली उपलब्ध गराउने समय आउँछ, Docz, Storybook र Styleguidist उत्कृष्ट विकल्पहरू हुन्।

अनुवादकबाट। Habré मा यो मेरो पहिलो अनुभव हो। यदि तपाइँ कुनै त्रुटिहरू फेला पार्नुभयो, वा लेख सुधार गर्न सुझावहरू छन् - व्यक्तिगत रूपमा लेख्नुहोस्।

स्रोत: www.habr.com