જીવન માર્ગદર્શિકા - MDX અને અન્ય ફ્રેમવર્ક

તમારી પાસે શ્રેષ્ઠ ઓપન સોર્સ પ્રોજેક્ટ હોઈ શકે છે, પરંતુ જો તેની પાસે સારા દસ્તાવેજો ન હોય, તો તે ક્યારેય બંધ ન થાય તેવી શક્યતા છે. ઑફિસમાં, સારા દસ્તાવેજો તમને સમાન પ્રશ્નોના જવાબો આપતા અટકાવશે. દસ્તાવેજીકરણ એ પણ સુનિશ્ચિત કરે છે કે જો મુખ્ય કર્મચારીઓ કંપની છોડી દે અથવા ભૂમિકા બદલાય તો લોકો પ્રોજેક્ટ સમજી શકે. જીવન માર્ગદર્શિકા ડેટા અખંડિતતાને સુનિશ્ચિત કરવામાં મદદ કરશે.

જો તમારે લાંબુ લખાણ લખવાની જરૂર હોય, તો માર્કડાઉન એ HTML નો શ્રેષ્ઠ વિકલ્પ છે. કેટલીકવાર માર્કડાઉન સિન્ટેક્સ પૂરતું નથી. આ કિસ્સામાં આપણે તેની અંદર HTML નો ઉપયોગ કરી શકીએ છીએ. ઉદાહરણ તરીકે, કસ્ટમ તત્વો. તેથી, જો તમે મૂળ વેબ ઘટકો સાથે ડિઝાઇન સિસ્ટમ બનાવી રહ્યા છો, તો તે સરળતાથી ટેક્સ્ટ દસ્તાવેજીકરણમાં સમાવી શકાય છે. જો તમે React (અથવા પ્રેક્ટ અથવા Vue જેવા અન્ય JSX ફ્રેમવર્ક) નો ઉપયોગ કરી રહ્યાં છો, તો તમે MDX નો ઉપયોગ કરીને તે જ વસ્તુ કરી શકો છો.

આ લેખ દસ્તાવેજીકરણ લખવા અને માર્ગદર્શિકા બનાવવા માટેના સાધનોની વ્યાપક ઝાંખી છે. અહીં સૂચિબદ્ધ તમામ સાધનો MDX નો ઉપયોગ કરતા નથી, પરંતુ તે વધુને વધુ દસ્તાવેજીકરણ સાધનોમાં સમાવિષ્ટ થઈ રહ્યું છે.

MDX શું છે?

ફાઈલ .mdx માર્કડાઉન જેવો જ વાક્યરચના ધરાવે છે, પરંતુ તમને ઇન્ટરેક્ટિવ JSX ઘટકો આયાત કરવા અને તમારી સામગ્રીમાં એમ્બેડ કરવાની મંજૂરી આપે છે. Vue ઘટકો માટે આધાર આલ્ફામાં છે. MDX સાથે કામ શરૂ કરવા માટે, ફક્ત "ક્રિએટ રિએક્ટ એપ" ઇન્સ્ટોલ કરો. Next.js અને Gatsby માટે પ્લગઈનો છે. ડોક્યુસૌરસના આગલા સંસ્કરણ (સંસ્કરણ 2) ને પણ મૂળ આધાર હશે.

ડોક્યુસૌરસ સાથે દસ્તાવેજીકરણ લખવું

ડોક્યુસૌરસ ફેસબુક પર લખ્યું. તેઓ પ્રતિક્રિયા સિવાય દરેક ઓપન સોર્સ પ્રોજેક્ટ પર તેનો ઉપયોગ કરે છે. કંપનીની બહાર તેનો ઉપયોગ Redux, Prettier, Gulp અને Babel દ્વારા થાય છે.

પ્રોજેક્ટ્સ કે જે ડોક્યુસૌરસનો ઉપયોગ કરે છે.

ડોક્યુસૌરસ લખવા માટે વાપરી શકાય છે કોઈપણ દસ્તાવેજીકરણ, માત્ર અગ્ર ભાગનું વર્ણન કરવા માટે નહીં. તે હૂડ હેઠળ પ્રતિક્રિયા ધરાવે છે, પરંતુ તેનો ઉપયોગ કરવા માટે તમારે તેનાથી પરિચિત હોવું જરૂરી નથી. તે તમારી માર્કડાઉન ફાઇલો લે છે, એક ચપટી જાદુ અને સારી રીતે સંરચિત, ફોર્મેટ કરેલ અને સુંદર ડિઝાઇન સાથે વાંચી શકાય તેવા દસ્તાવેજો તૈયાર છે.

Redux વેબસાઇટ પર તમે પ્રમાણભૂત ડોક્યુસૌરસ ટેમ્પલેટ જોઈ શકો છો

ડોક્યુસૌરસ સાથે બનેલી વેબસાઇટ્સમાં માર્કડાઉન-આધારિત બ્લોગ પણ શામેલ હોઈ શકે છે. Prism.js સિન્ટેક્સ હાઇલાઇટિંગ માટે તરત જ જોડાયેલ છે. હકીકત એ છે કે ડોક્યુસૌરસ પ્રમાણમાં તાજેતરમાં દેખાયો હોવા છતાં, તે સ્ટેકશેર પર 2018 ના શ્રેષ્ઠ સાધન તરીકે ઓળખાય છે.

અન્ય સામગ્રી બનાવવાના વિકલ્પો

ડોક્યુસૌરસ ખાસ કરીને દસ્તાવેજીકરણ બનાવવા માટે રચાયેલ છે. અલબત્ત, વેબસાઇટ બનાવવાની એક મિલિયન અને એક રીત છે - તમે કોઈપણ ભાષા, CMSમાં તમારું પોતાનું સોલ્યુશન જમાવી શકો છો અથવા સ્ટેટિક સાઇટ જનરેટરનો ઉપયોગ કરી શકો છો.

ઉદાહરણ તરીકે, React, IBM ડિઝાઇન સિસ્ટમ, Apollo અને Ghost CMS માટે દસ્તાવેજીકરણ ગેટ્સબીનો ઉપયોગ કરે છે - એક સ્થિર સાઇટ જનરેટર જેનો ઉપયોગ બ્લોગ્સ માટે થાય છે. જો તમે Vue સાથે કામ કરો છો, તો VuePress તમારા માટે સારો વિકલ્પ છે. બીજો વિકલ્પ Python - MkDocs માં લખેલા જનરેટરનો ઉપયોગ કરવાનો છે. તે ઓપન સોર્સ છે અને એક YAML ફાઇલનો ઉપયોગ કરીને ગોઠવેલ છે. GitBook પણ એક સારો વિકલ્પ છે, પરંતુ તે માત્ર જાહેર અને બિન-વ્યાવસાયિક ટીમો માટે જ મફત છે. તમે Git નો ઉપયોગ કરીને માર્ડાઉન ફાઇલો પણ અપલોડ કરી શકો છો અને Github માં તેમની સાથે કામ કરી શકો છો.

દસ્તાવેજીકરણ ઘટકો: ડોકઝ, સ્ટોરીબુક અને સ્ટાઇલગાઇડિસ્ટ

માર્ગદર્શિકા, સિસ્ટમ ડિઝાઇન, ઘટક પુસ્તકાલયો - તમે તેમને જે પણ કહો છો, તે તાજેતરમાં ખૂબ જ લોકપ્રિય બન્યું છે. રિએક્ટ જેવા ઘટક ફ્રેમવર્કના આગમન અને અહીં જણાવેલ સાધનોએ તેમને વેનિટી પ્રોજેક્ટમાંથી ઉપયોગી સાધનોમાં પરિવર્તિત કર્યા છે.

સ્ટોરીબુક, ડોકઝ અને સ્ટાઇલગાઇડિસ્ટ બધા એક જ કામ કરે છે: ઇન્ટરેક્ટિવ તત્વો પ્રદર્શિત કરો અને તેમના API દસ્તાવેજ કરો. એક પ્રોજેક્ટમાં ડઝનેક અથવા તો સેંકડો ઘટકો હોઈ શકે છે - બધા વિવિધ રાજ્યો અને શૈલીઓ સાથે. જો તમે ઘટકોનો ફરીથી ઉપયોગ કરવા માંગતા હો, તો લોકોને તે જાણવાની જરૂર છે. આ કરવા માટે, ફક્ત ઘટકોની સૂચિ બનાવો. દિશાનિર્દેશો તમારા તમામ ઘટકોની સરળતાથી શોધી શકાય તેવી વિહંગાવલોકન પ્રદાન કરે છે. આ દ્રશ્ય સુસંગતતા જાળવવામાં અને પુનરાવર્તિત કાર્યને ટાળવામાં મદદ કરે છે.

આ સાધનો વિવિધ રાજ્યોને જોવાની અનુકૂળ રીત પ્રદાન કરે છે. વાસ્તવિક એપ્લિકેશનના સંદર્ભમાં ઘટકની દરેક સ્થિતિનું પુનઃઉત્પાદન કરવું મુશ્કેલ હોઈ શકે છે. વાસ્તવિક એપ્લિકેશન પર ક્લિક કરવાને બદલે, તે એક અલગ ઘટક વિકસાવવા યોગ્ય છે. હાર્ડ-ટુ-રીચ સ્ટેટ્સ (જેમ કે લોડિંગ સ્ટેટ્સ) સિમ્યુલેટ કરી શકાય છે.

વિવિધ રાજ્યોના દ્રશ્ય પ્રદર્શન અને ગુણધર્મોની સૂચિ સાથે, સામગ્રીનું સામાન્ય વર્ણન - ડિઝાઇન તર્ક, ઉપયોગના કેસ અથવા વપરાશકર્તા પરીક્ષણ પરિણામોનું વર્ણન લખવું ઘણીવાર જરૂરી છે. માર્કડાઉન શીખવા માટે ખૂબ જ સરળ છે - આદર્શ રીતે, દિશાનિર્દેશો ડિઝાઇનર્સ અને વિકાસકર્તાઓ માટે વહેંચાયેલ સંસાધન હોવા જોઈએ. Docz, Styleguidist અને 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>બિલ્ટ-ઇન કોડપેન અથવા કોડસેન્ડબોક્સનું એનાલોગ બનાવવા માટે - એટલે કે, તમે તમારા ઘટકને જુઓ છો અને તેને સંપાદિત કરી શકો છો.

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

<Props> આપેલ પ્રતિક્રિયા ઘટક, ડિફોલ્ટ મૂલ્યો અને મિલકત જરૂરી છે કે કેમ તે માટે તમામ ઉપલબ્ધ ગુણધર્મો બતાવશે.

<Props of={Button} />

અંગત રીતે, મને આ MDX આધારિત અભિગમ સમજવા માટે સૌથી સરળ અને કામ કરવા માટે સૌથી સરળ લાગે છે.

જો તમે ગેટ્સબી સ્ટેટિક સાઇટ જનરેટરના ચાહક છો, તો Docz એક સરસ એકીકરણ પ્રદાન કરે છે.

શૈલી માર્ગદર્શિકા

ડોકઝની જેમ, માર્કડાઉન સિન્ટેક્સનો ઉપયોગ કરીને ઉદાહરણો લખવામાં આવે છે. Styleguidist નિયમિત ફાઇલોમાં માર્કડાઉન કોડ બ્લોક્સ (ટ્રિપલ અવતરણ) નો ઉપયોગ કરે છે .md ફાઇલો, MDX નહીં.

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

માર્કડાઉનમાં કોડ બ્લોક સામાન્ય રીતે માત્ર કોડ દર્શાવે છે. Styleguidist નો ઉપયોગ કરતી વખતે, ભાષા ટેગ સાથે કોડનો કોઈપણ બ્લોક js, jsx અથવા javascript પ્રતિક્રિયા ઘટક તરીકે રેન્ડર કરશે. Docz ની જેમ, કોડ સંપાદનયોગ્ય છે - તમે ગુણધર્મો બદલી શકો છો અને તરત જ પરિણામ જોઈ શકો છો.

સ્ટાઇલગાઇડિસ્ટ પ્રોપટાઇપ્સ, ફ્લો અથવા ટાઇપસ્ક્રિપ્ટ ઘોષણાઓમાંથી આપમેળે પ્રોપર્ટી ટેબલ બનાવશે.

Styleguidist હાલમાં React અને Vue ને સપોર્ટ કરે છે.

સ્ટોરીબુક

સ્ટોરીબુક પોતાને "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>

સ્ટોરીબુકની નવી સુવિધાઓ આવતા થોડા મહિનામાં ધીમે ધીમે બહાર આવશે અને એવું લાગે છે કે તે એક મોટું પગલું હશે.

પરિણામો

પેટર્ન લાઇબ્રેરીના ફાયદાઓ માધ્યમ પર લાખો લેખોમાં વખાણવામાં આવે છે. જ્યારે સારી રીતે કરવામાં આવે છે, ત્યારે તેઓ સંબંધિત ઉત્પાદનો બનાવવા અને ઓળખ જાળવવાનું સરળ બનાવે છે. અલબત્ત, આમાંથી કોઈ પણ સાધન જાદુઈ રીતે ડિઝાઇન સિસ્ટમ બનાવશે નહીં. આને સાવચેત ડિઝાઇન અને CSSની જરૂર છે. પરંતુ જ્યારે ડિઝાઇન સિસ્ટમને સમગ્ર કંપની માટે સુલભ બનાવવાનો સમય આવે છે, ત્યારે Docz, Storybook અને Styleguidist શ્રેષ્ઠ વિકલ્પો છે.

અનુવાદક તરફથી. હેબ્રે પર આ મારો પહેલો અનુભવ છે. જો તમને કોઈ અચોક્કસતા જણાય, અથવા લેખ સુધારવા માટે સૂચનો હોય, તો મને વ્યક્તિગત સંદેશમાં લખો.

સોર્સ: www.habr.com