തത്സമയ മാർഗ്ഗനിർദ്ദേശങ്ങൾ - MDX ഉം മറ്റ് ചട്ടക്കൂടുകളും

നിങ്ങൾക്ക് മികച്ച ഓപ്പൺ സോഴ്‌സ് പ്രോജക്‌റ്റ് ഉണ്ടായിരിക്കാം, പക്ഷേ അതിന് നല്ല ഡോക്യുമെന്റേഷൻ ഇല്ലെങ്കിൽ, അത് ഒരിക്കലും ആരംഭിക്കാൻ സാധ്യതയില്ല. ഓഫീസിൽ, നല്ല ഡോക്യുമെന്റേഷൻ ഒരേ ചോദ്യങ്ങൾക്ക് ഉത്തരം നൽകുന്നതിൽ നിന്ന് നിങ്ങളെ തടയും. പ്രധാന ജീവനക്കാർ കമ്പനി വിടുകയോ റോളുകൾ മാറുകയോ ചെയ്താൽ ആളുകൾക്ക് പ്രോജക്റ്റ് മനസ്സിലാക്കാൻ കഴിയുമെന്ന് ഡോക്യുമെന്റേഷൻ ഉറപ്പാക്കുന്നു. ലിവിംഗ് മാർഗ്ഗനിർദ്ദേശങ്ങൾ ഡാറ്റയുടെ സമഗ്രത ഉറപ്പാക്കാൻ സഹായിക്കും.

നിങ്ങൾക്ക് ദൈർഘ്യമേറിയ വാചകം എഴുതണമെങ്കിൽ, HTML-നുള്ള മികച്ച ബദലാണ് മാർക്ക്ഡൗൺ. ചിലപ്പോൾ മാർക്ക്ഡൗൺ വാക്യഘടന മതിയാകില്ല. ഈ സാഹചര്യത്തിൽ നമുക്ക് അതിനുള്ളിൽ HTML ഉപയോഗിക്കാം. ഉദാഹരണത്തിന്, ഇഷ്‌ടാനുസൃത ഘടകങ്ങൾ. അതിനാൽ, നിങ്ങൾ നേറ്റീവ് വെബ് ഘടകങ്ങളുള്ള ഒരു ഡിസൈൻ സിസ്റ്റം നിർമ്മിക്കുകയാണെങ്കിൽ, അവ ടെക്സ്റ്റ് ഡോക്യുമെന്റേഷനിൽ എളുപ്പത്തിൽ ഉൾപ്പെടുത്താം. നിങ്ങൾ React (അല്ലെങ്കിൽ Preact അല്ലെങ്കിൽ Vue പോലുള്ള മറ്റേതെങ്കിലും JSX ചട്ടക്കൂടാണ്) ഉപയോഗിക്കുന്നതെങ്കിൽ, MDX ഉപയോഗിച്ച് നിങ്ങൾക്ക് ഇത് തന്നെ ചെയ്യാൻ കഴിയും.

ഡോക്യുമെന്റേഷൻ എഴുതുന്നതിനും മാർഗ്ഗനിർദ്ദേശങ്ങൾ സൃഷ്ടിക്കുന്നതിനുമുള്ള ഉപകരണങ്ങളുടെ വിശാലമായ അവലോകനമാണ് ഈ ലേഖനം. ഇവിടെ ലിസ്റ്റുചെയ്തിരിക്കുന്ന എല്ലാ ഉപകരണങ്ങളും MDX ഉപയോഗിക്കുന്നില്ല, പക്ഷേ ഇത് ഡോക്യുമെന്റേഷൻ ടൂളുകളിൽ കൂടുതലായി ഉൾപ്പെടുത്തിയിട്ടുണ്ട്.

എന്താണ് MDX?

ഫയല് .mdx മാർക്ക്ഡൗണിന്റെ അതേ വാക്യഘടനയുണ്ട്, എന്നാൽ ഇന്ററാക്ടീവ് JSX ഘടകങ്ങൾ ഇറക്കുമതി ചെയ്യാനും അവ നിങ്ങളുടെ ഉള്ളടക്കത്തിൽ ഉൾപ്പെടുത്താനും നിങ്ങളെ അനുവദിക്കുന്നു. വ്യൂ ഘടകങ്ങൾക്കുള്ള പിന്തുണ ആൽഫയിലാണ്. MDX-ൽ പ്രവർത്തിക്കാൻ തുടങ്ങാൻ, "ക്രിയേറ്റ് റിയാക്റ്റ് ആപ്പ്" ഇൻസ്റ്റാൾ ചെയ്യുക. Next.js, Gatsby എന്നിവയ്‌ക്കായി പ്ലഗിനുകൾ ഉണ്ട്. ഡോക്യുസോറസിന്റെ അടുത്ത പതിപ്പിന് (പതിപ്പ് 2) നേറ്റീവ് പിന്തുണയും ഉണ്ടായിരിക്കും.

ഡോക്യുസോറസ് ഉപയോഗിച്ച് ഡോക്യുമെന്റേഷൻ എഴുതുന്നു

ഡോക്യുസോറസ് ഫേസ്ബുക്കിൽ കുറിച്ചു. റിയാക്ട് ഒഴികെയുള്ള എല്ലാ ഓപ്പൺ സോഴ്‌സ് പ്രോജക്റ്റുകളിലും അവർ ഇത് ഉപയോഗിക്കുന്നു. കമ്പനിക്ക് പുറത്ത് ഇത് Redux, Prettier, Gulp, Babel എന്നിവർ ഉപയോഗിക്കുന്നു.

ഡോക്യുസോറസ് ഉപയോഗിക്കുന്ന പ്രോജക്റ്റുകൾ.

എഴുതാൻ ഡോക്യുസോറസ് ഉപയോഗിക്കാം ഏതെങ്കിലും ഡോക്യുമെന്റേഷൻ, മുൻഭാഗത്തെ വിവരിക്കാൻ മാത്രമല്ല. ഇതിന് ഹുഡിന് കീഴിൽ റിയാക്റ്റ് ഉണ്ട്, എന്നാൽ ഇത് ഉപയോഗിക്കാൻ നിങ്ങൾക്ക് ഇത് പരിചിതമായിരിക്കണമെന്നില്ല. ഇത് നിങ്ങളുടെ മാർക്ക്ഡൗൺ ഫയലുകൾ എടുക്കുന്നു, ഒരു നുള്ള് മാജിക്, നല്ല ഘടനയുള്ള, ഫോർമാറ്റ് ചെയ്‌തതും വായിക്കാനാകുന്നതുമായ ഡോക്യുമെന്റേഷൻ തയ്യാറാണ്.

Redux വെബ്സൈറ്റിൽ നിങ്ങൾക്ക് സാധാരണ Docusaurus ടെംപ്ലേറ്റ് കാണാൻ കഴിയും

Docusaurus ഉപയോഗിച്ച് നിർമ്മിച്ച വെബ്‌സൈറ്റുകളിൽ Markdown അടിസ്ഥാനമാക്കിയുള്ള ബ്ലോഗും ഉൾപ്പെടുത്താം. വാക്യഘടന ഹൈലൈറ്റിംഗിനായി Prism.js ഉടനടി ബന്ധിപ്പിച്ചിരിക്കുന്നു. Docusaurus താരതമ്യേന അടുത്തിടെ പ്രത്യക്ഷപ്പെട്ടിട്ടുണ്ടെങ്കിലും, StackShare-ൽ 2018 ലെ ഏറ്റവും മികച്ച ഉപകരണമായി ഇത് അംഗീകരിക്കപ്പെട്ടു.

മറ്റ് ഉള്ളടക്ക സൃഷ്ടിക്കൽ ഓപ്ഷനുകൾ

ഡോക്യുമെന്റേഷൻ സൃഷ്ടിക്കുന്നതിനായി പ്രത്യേകം രൂപകൽപ്പന ചെയ്തിട്ടുള്ളതാണ് ഡോക്യുസോറസ്. തീർച്ചയായും, ഒരു വെബ്‌സൈറ്റ് നിർമ്മിക്കുന്നതിന് ദശലക്ഷക്കണക്കിന് വഴികളുണ്ട് - നിങ്ങൾക്ക് ഏത് ഭാഷയിലും, CMS-ലും, അല്ലെങ്കിൽ ഒരു സ്റ്റാറ്റിക് സൈറ്റ് ജനറേറ്റർ ഉപയോഗിക്കാനും നിങ്ങളുടെ സ്വന്തം പരിഹാരം വിന്യസിക്കാം.

ഉദാഹരണത്തിന്, റിയാക്റ്റ്, ഐബിഎം ഡിസൈൻ സിസ്റ്റം, അപ്പോളോ, ഗോസ്റ്റ് സിഎംഎസ് എന്നിവയ്‌ക്കായുള്ള ഡോക്യുമെന്റേഷൻ ഗാറ്റ്‌സ്ബി ഉപയോഗിക്കുന്നു - ബ്ലോഗുകൾക്കായി പലപ്പോഴും ഉപയോഗിക്കുന്ന ഒരു സ്റ്റാറ്റിക് സൈറ്റ് ജനറേറ്റർ. നിങ്ങൾ Vue-യിൽ പ്രവർത്തിക്കുകയാണെങ്കിൽ, VuePress നിങ്ങൾക്ക് ഒരു നല്ല ഓപ്ഷനാണ്. Python - MkDocs-ൽ എഴുതിയ ഒരു ജനറേറ്റർ ഉപയോഗിക്കുക എന്നതാണ് മറ്റൊരു ഓപ്ഷൻ. ഇത് ഓപ്പൺ സോഴ്‌സ് ആണ് കൂടാതെ ഒരൊറ്റ YAML ഫയൽ ഉപയോഗിച്ച് ക്രമീകരിച്ചിരിക്കുന്നു. GitBook ഒരു നല്ല ഓപ്ഷനാണ്, എന്നാൽ ഇത് പൊതു, വാണിജ്യേതര ടീമുകൾക്ക് മാത്രം സൗജന്യമാണ്. നിങ്ങൾക്ക് Git ഉപയോഗിച്ച് മാർഡൗൺ ഫയലുകൾ അപ്‌ലോഡ് ചെയ്യാനും Github-ൽ അവയ്‌ക്കൊപ്പം പ്രവർത്തിക്കാനും കഴിയും.

ഡോക്യുമെന്റിംഗ് ഘടകങ്ങൾ: Docz, Storybook, Styleguidist

മാർഗ്ഗനിർദ്ദേശങ്ങൾ, സിസ്റ്റം ഡിസൈൻ, ഘടക ലൈബ്രറികൾ - നിങ്ങൾ അവയെ എന്ത് വിളിച്ചാലും, ഈയിടെയായി അത് വളരെ പ്രചാരത്തിലുണ്ട്. റിയാക്റ്റ് പോലുള്ള ഘടക ചട്ടക്കൂടുകളുടെ ആവിർഭാവവും ഇവിടെ പരാമർശിച്ചിരിക്കുന്ന ഉപകരണങ്ങളും അവയെ വാനിറ്റി പ്രോജക്റ്റുകളിൽ നിന്ന് ഉപയോഗപ്രദമായ ഉപകരണങ്ങളാക്കി മാറ്റി.

Storybook, Docz, Styleguidist എന്നിവയെല്ലാം ഒരേ കാര്യം ചെയ്യുന്നു: സംവേദനാത്മക ഘടകങ്ങൾ പ്രദർശിപ്പിക്കുകയും അവയുടെ 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 അടിസ്ഥാനമാക്കിയുള്ള സമീപനം മനസ്സിലാക്കാൻ ഏറ്റവും എളുപ്പമുള്ളതും പ്രവർത്തിക്കാൻ എളുപ്പമുള്ളതുമാണെന്ന് ഞാൻ കാണുന്നു.

നിങ്ങൾ Gatsby സ്റ്റാറ്റിക് സൈറ്റ് ജനറേറ്ററിന്റെ ആരാധകനാണെങ്കിൽ, Docz ഒരു മികച്ച സംയോജനം വാഗ്ദാനം ചെയ്യുന്നു.

സ്റ്റൈൽ ഗൈഡ്

Docz പോലെ, Markdown വാക്യഘടന ഉപയോഗിച്ചാണ് ഉദാഹരണങ്ങൾ എഴുതുന്നത്. സാധാരണ ഫയലുകളിൽ Styleguidist Markdown കോഡ് ബ്ലോക്കുകൾ (ട്രിപ്പിൾ ഉദ്ധരണികൾ) ഉപയോഗിക്കുന്നു .md ഫയലുകൾ, MDX അല്ല.

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

മാർക്ക്ഡൗണിലെ കോഡ് ബ്ലോക്കുകൾ സാധാരണയായി കോഡ് കാണിക്കുന്നു. Styleguidist ഉപയോഗിക്കുമ്പോൾ, ഒരു ഭാഷാ ടാഗുള്ള കോഡിന്റെ ഏതെങ്കിലും ബ്ലോക്ക് js, jsx അഥവാ javascript ഒരു പ്രതികരണ ഘടകമായി റെൻഡർ ചെയ്യും. Docz പോലെ, കോഡ് എഡിറ്റ് ചെയ്യാവുന്നതാണ് - നിങ്ങൾക്ക് പ്രോപ്പർട്ടികൾ മാറ്റാനും തൽക്ഷണം ഫലം കാണാനും കഴിയും.

PropTypes, Flow അല്ലെങ്കിൽ Typescript പ്രഖ്യാപനങ്ങളിൽ നിന്ന് Styleguidist സ്വയമേവ ഒരു പ്രോപ്പർട്ടി ടേബിൾ സൃഷ്ടിക്കും.

Styleguidist നിലവിൽ React, Vue എന്നിവയെ പിന്തുണയ്ക്കുന്നു.

സ്റ്റോറിബുക്ക്

സ്റ്റോറിബുക്ക് സ്വയം ഒരു "UI ഘടക വികസന പരിസ്ഥിതി" ആയി നിലകൊള്ളുന്നു. Markdown അല്ലെങ്കിൽ MDX ഫയലുകൾക്കുള്ളിൽ ഉദാഹരണ ഘടകങ്ങൾ എഴുതുന്നതിനുപകരം, നിങ്ങൾ എഴുതുക ചരിത്രം Javascript ഫയലുകൾക്കുള്ളിൽ. കഥ ഒരു ഘടകത്തിന്റെ പ്രത്യേക അവസ്ഥ രേഖപ്പെടുത്തുക. ഉദാഹരണത്തിന്, ഒരു ഘടകത്തിന് ലോഡ് ചെയ്ത അവസ്ഥയ്ക്കും അപ്രാപ്തമാക്കിയ അവസ്ഥയ്ക്കും ചരിത്രങ്ങൾ ഉണ്ടായിരിക്കാം (അപ്രാപ്‌തമാക്കി).

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

Styleguidist, Docz എന്നിവയേക്കാൾ വളരെ സങ്കീർണ്ണമാണ് സ്റ്റോറിബുക്ക്. എന്നാൽ അതേ സമയം, ഇത് ഏറ്റവും ജനപ്രിയമായ ഓപ്ഷനാണ്; പ്രോജക്റ്റിന് Github-ൽ 36-ലധികം നക്ഷത്രങ്ങളുണ്ട്. 000 സംഭാവകരും മുഴുവൻ സമയ ജീവനക്കാരും ഉള്ള ഒരു ഓപ്പൺ സോഴ്‌സ് പ്രോജക്റ്റാണിത്. ഇത് Airbnb, Algolia, Atlassian, Lyft, Salesforce എന്നിവ ഉപയോഗിക്കുന്നു. സ്റ്റോറിബുക്ക് എതിരാളികളേക്കാൾ കൂടുതൽ ചട്ടക്കൂടുകളെ പിന്തുണയ്ക്കുന്നു - റിയാക്റ്റ്, റിയാക്ട് നേറ്റീവ്, വ്യൂ, ആംഗുലാർ, മിത്രിൽ, എംബർ, റയറ്റ്, സ്വെൽറ്റ്, റെഗുലർ എച്ച്ടിഎംഎൽ.

ഭാവിയിൽ 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