ජීවන මාර්ගෝපදේශ - MDX සහ අනෙකුත් රාමු

ඔබට හොඳම විවෘත මූලාශ්‍ර ව්‍යාපෘතියක් තිබිය හැක, නමුත් එයට හොඳ ලියකියවිලි නොමැති නම්, එය කිසිදා ආරම්භ නොවන අවස්ථා තිබේ. කාර්යාලයේදී, හොඳ ලියකියවිලි එකම ප්‍රශ්නවලට පිළිතුරු සැපයීම වළක්වයි. ප්‍රධාන සේවකයින් සමාගම හැර ගියහොත් හෝ භූමිකාවන් වෙනස් වුවහොත් ව්‍යාපෘතිය මිනිසුන්ට තේරුම් ගත හැකි බව ලේඛනගත කිරීම සහතික කරයි. ජීවන මාර්ගෝපදේශ දත්ත අඛණ්ඩතාව සහතික කිරීමට උපකාරී වනු ඇත.

ඔබට දිගු අකුරු ලිවීමට අවශ්‍ය නම්, Markdown යනු HTML සඳහා කදිම විකල්පයකි. සමහර විට Markdown syntax ප්රමාණවත් නොවේ. මේකෙදි අපිට ඒක ඇතුලේ HTML පාවිච්චි කරන්න පුළුවන්. උදාහරණයක් ලෙස, අභිරුචි අංග. එබැවින්, ඔබ ස්වදේශීය වෙබ් සංරචක සහිත නිර්මාණ පද්ධතියක් ගොඩනඟන්නේ නම්, ඒවා පහසුවෙන් පෙළ ලේඛනගත කිරීමට ඇතුළත් කළ හැකිය. ඔබ React (හෝ Preact හෝ Vue වැනි වෙනත් JSX රාමුවක්) භාවිතා කරන්නේ නම්, ඔබට MDX සමඟ එකම දේ කළ හැකිය.

මෙම ලිපිය ලේඛන ලිවීම සහ මාර්ගෝපදේශ නිර්මාණය කිරීම සඳහා මෙවලම් පිළිබඳ පුළුල් දළ විශ්ලේෂණයකි. මෙහි ලැයිස්තුගත කර ඇති සියලුම මෙවලම් MDX භාවිතා නොකරයි, නමුත් එය වැඩි වැඩියෙන් ලේඛන මෙවලම්වල ඇතුළත් වේ.

MDX යනු කුමක්ද?

ගොනුව .mdx Markdown හා සමාන වාක්‍ය ඛණ්ඩයක් ඇත, නමුත් ඔබට අන්තර්ක්‍රියාකාරී JSX සංරචක ආයාත කිරීමට සහ ඒවා ඔබේ අන්තර්ගතයට කාවැද්දීමට ඉඩ සලසයි. Vue සංරචක සඳහා සහය ඇල්ෆා වලින් ඇත. MDX සමඟ වැඩ කිරීම ආරම්භ කිරීමට, "Create React App" ස්ථාපනය කරන්න. Next.js සහ Gatsby සඳහා ප්ලගීන තිබේ. Docusaurus හි මීළඟ අනුවාදයට (අනුවාදය 2) ස්වදේශීය සහාය ද ඇත.

Docusaurus සමඟ ලියකියවිලි ලිවීම

Docusaurus ෆේස්බුක් හි ලිවීය. ඔවුන් එය ප්‍රතික්‍රියා හැර සෑම විවෘත මූලාශ්‍ර ව්‍යාපෘතියකම භාවිතා කරයි. සමාගමෙන් පිටත එය Redux, Prettier, Gulp සහ Babel විසින් භාවිතා කරනු ලැබේ.

Docusaurus භාවිතා කරන ව්‍යාපෘති.

ලිවීමට Docusaurus භාවිතා කළ හැකිය කිසිවක් නැත ලියකියවිලි, ඉදිරිපස විස්තර කිරීමට පමණක් නොවේ. එහි හුඩ් යටතේ ප්‍රතික්‍රියා ඇත, නමුත් එය භාවිතා කිරීමට ඔබ එය හුරුපුරුදු විය යුතු නැත. එය ඔබගේ Markdown ගොනු ගනී, මැජික් පොකුරක් සහ හොඳින් ව්‍යුහගත, හැඩතල ගැන්වූ සහ කියවිය හැකි ලියකියවිලි අලංකාර මෝස්තරයක් සූදානම් වේ.

Redux වෙබ් අඩවියේ ඔබට සම්මත Docusaurus අච්චුව දැකිය හැකිය

Docusaurus සමඟ ගොඩනගා ඇති වෙබ් අඩවි වලට Markdown මත පදනම් වූ බ්ලොග් අඩවියක් ද ඇතුළත් විය හැකිය. Prism.js සින්ටැක්ස් උද්දීපනය සඳහා වහාම සම්බන්ධ වේ. Docusaurus සාපේක්ෂව මෑතකදී දර්ශනය වූවද, එය StackShare හි 2018 හොඳම මෙවලම ලෙස පිළිගැනේ.

වෙනත් අන්තර්ගත නිර්මාණ විකල්ප

Docusaurus විශේෂයෙන් නිර්මාණය කර ඇත්තේ ලේඛන නිර්මාණය කිරීම සඳහා ය. ඇත්ත වශයෙන්ම, වෙබ් අඩවියක් සෑදීමට මිලියනයක් සහ එක් ක්‍රම තිබේ - ඔබට ඕනෑම භාෂාවකින් ඔබේම විසඳුමක් යෙදිය හැකිය, CMS, හෝ ස්ථිතික අඩවි උත්පාදකයක් භාවිතා කරන්න.

උදාහරණයක් ලෙස, React, IBM සැලසුම් පද්ධතිය, Apollo සහ Ghost CMS සඳහා ලේඛනගත කිරීම් Gatsby - බ්ලොග් සඳහා නිතර භාවිතා කරන ස්ථිතික අඩවි උත්පාදකයක් භාවිතා කරයි. ඔබ Vue සමඟ වැඩ කරන්නේ නම්, VuePress ඔබට හොඳ විකල්පයකි. තවත් විකල්පයක් වන්නේ Python - MkDocs හි ලියා ඇති උත්පාදක යන්ත්රයක් භාවිතා කිරීමයි. එය විවෘත මූලාශ්‍රයක් වන අතර තනි YAML ගොනුවක් භාවිතයෙන් වින්‍යාස කර ඇත. GitBook ද හොඳ විකල්පයකි, නමුත් එය පොදු සහ වාණිජ නොවන කණ්ඩායම් සඳහා පමණක් නොමිලේ. ඔබට Git භාවිතයෙන් සරලව මාර්ඩවුන් ගොනු උඩුගත කර Github හි ඒවා සමඟ වැඩ කළ හැකිය.

ලේඛන සංරචක: Docz, Storybook සහ Styleguidist

මාර්ගෝපදේශ, පද්ධති සැලසුම්, සංරචක පුස්තකාල - ඔබ ඒවා කුමක් ලෙස හැඳින්වුවද, එය මෑතකදී ඉතා ජනප්‍රිය වී ඇත. ප්‍රතික්‍රියා වැනි සංරචක රාමු පැමිණීම සහ මෙහි සඳහන් මෙවලම් ඒවා නිෂ්ඵල ව්‍යාපෘතිවල සිට ප්‍රයෝජනවත් මෙවලම් බවට පරිවර්තනය කර ඇත.

Storybook, Docz සහ Styleguidist සියල්ලම කරන්නේ එකම දෙයකි: අන්තර්ක්‍රියාකාරී මූලද්‍රව්‍ය සංදර්ශන කිරීම සහ ඒවායේ API ලේඛනගත කිරීම. ව්‍යාපෘතියකට දුසිම් ගනනක් හෝ සංරචක සිය ගණනක් තිබිය හැක - සියල්ල විවිධ ප්‍රාන්ත සහ මෝස්තර සහිතයි. ඔබට සංරචක නැවත භාවිතා කිරීමට අවශ්‍ය නම්, ඒවා පවතින බව මිනිසුන් දැන සිටිය යුතුය. මෙය සිදු කිරීම සඳහා, සංරචක ලැයිස්තුගත කරන්න. මාර්ගෝපදේශ මඟින් ඔබගේ සියලුම සංරචක පිළිබඳ පහසුවෙන් සොයා ගත හැකි දළ විශ්ලේෂණයක් සපයයි. මෙය දෘශ්‍ය අනුකූලතාව පවත්වා ගැනීමට සහ නැවත නැවත වැඩ කිරීමෙන් වැළකී සිටීමට උපකාරී වේ.

මෙම මෙවලම් විවිධ තත්වයන් බැලීමට පහසු ක්රමයක් සපයයි. සැබෑ යෙදුමක සන්දර්භය තුළ සංරචකයක එක් එක් තත්වය ප්‍රතිනිෂ්පාදනය කිරීම අපහසු විය හැක. සැබෑ යෙදුම මත ක්ලික් කිරීම වෙනුවට, වෙනම සංරචකයක් සංවර්ධනය කිරීම වටී. ළඟා වීමට අපහසු තත්වයන් (පූරණය වන තත්වයන් වැනි) අනුකරණය කළ හැක.

විවිධ ප්‍රාන්තවල දෘශ්‍ය නිරූපණයක් සහ ගුණාංග ලැයිස්තුවක් සමඟින්, බොහෝ විට අන්තර්ගතය පිළිබඳ සාමාන්‍ය විස්තරයක් ලිවීම අවශ්‍ය වේ - සැලසුම් තාර්කිකතා, භාවිත අවස්ථා හෝ පරිශීලක පරීක්ෂණ ප්‍රතිඵලවල විස්තර. Markdown ඉගෙන ගැනීමට ඉතා පහසුයි - ඉතා මැනවින්, මාර්ගෝපදේශ නිර්මාණකරුවන් සහ සංවර්ධකයින් සඳහා හවුල් සම්පතක් විය යුතුය. Docz, Styleguidist සහ Storybook පහසුවෙන් Markdown සංරචක සමඟ මිශ්‍ර කිරීමට ක්‍රමයක් ඉදිරිපත් කරයි.

Docz

දැනට Docz ක්‍රියා කරන්නේ React සමඟ පමණි, නමුත් Preact, Vue සහ web සංරචක සඳහා සහය දැක්වීම සඳහා සක්‍රිය වැඩ සිදු වෙමින් පවතී. 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 පදනම් වූ ප්‍රවේශය තේරුම් ගැනීමට පහසුම සහ වැඩ කිරීමට පහසුම බව මට පෙනී යයි.

ඔබ Gatsby ස්ථිතික අඩවි උත්පාදකයේ රසිකයෙක් නම්, Docz විශිෂ්ට ඒකාබද්ධතාවයක් ලබා දෙයි.

විලාසිතා මාර්ගෝපදේශය

Docz මෙන්, උදාහරණ ලියන්නේ Markdown syntax භාවිතා කරමිනි. Styleguidist සාමාන්‍ය ගොනු වල Markdown code blocks (ත්‍රිත්ව උපුටා දැක්වීම්) භාවිතා කරයි .md ගොනු, MDX නොවේ.

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

Markdown හි කේත අවහිර කිරීම් සාමාන්‍යයෙන් කේතය පෙන්වයි. Styleguidist භාවිතා කරන විට, භාෂා ටැගයක් සහිත ඕනෑම කේතයක් js, jsx හෝ javascript ප්‍රතික්‍රියා සංරචකයක් ලෙස ලබා දෙනු ඇත. Docz මෙන්, කේතය සංස්කරණය කළ හැකිය - ඔබට ගුණාංග වෙනස් කර ක්ෂණිකව ප්රතිඵලය දැකිය හැකිය.

Styleguidist විසින් PropTypes, Flow හෝ Typescript declaration වෙතින් දේපල වගුවක් ස්වයංක්‍රීයව සාදනු ඇත.

Styleguidist දැනට React සහ Vue සඳහා සහය දක්වයි.

කතන්දර පොත

කතන්දර පොත "UI සංරචක සංවර්ධන පරිසරයක්" ලෙස ස්ථානගත කරයි. Markdown හෝ ​​MDX ගොනු තුළ උදාහරණ සංරචක ලිවීම වෙනුවට, ඔබ ලියන්න කථා Javascript ගොනු ඇතුළත. කතාව සංරචකයක නිශ්චිත තත්ත්වය ලේඛනගත කරන්න. උදාහරණයක් ලෙස, සංරචකයකට පටවන ලද තත්වයක් සහ ආබාධිත තත්වයක් සඳහා ඉතිහාසයක් තිබිය හැක (අක්‍රීයයි).

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

Storybook Styleguidist සහ Docz වලට වඩා සංකීර්ණයි. නමුත් ඒ සමඟම, මෙය වඩාත් ජනප්‍රිය විකල්පයයි; ව්‍යාපෘතියට Github හි තරු 36 කට වඩා ඇත. එය දායකයින් 000ක් සහ පූර්ණ කාලීන කාර්ය මණ්ඩලයක් සහිත විවෘත මූලාශ්‍ර ව්‍යාපෘතියකි. එය Airbnb, Algolia, Atlassian, Lyft සහ Salesforce විසින් භාවිතා කරනු ලැබේ. කතන්දර පොත තරඟකරුවන්ට වඩා වැඩි රාමු සඳහා සහය දක්වයි - ප්‍රතික්‍රියා, ප්‍රතික්‍රියා ස්වදේශීය, Vue, කෝණික, මිත්‍රිල්, එම්බර්, කැරලි, ස්වෙල්ට් සහ සාමාන්‍ය 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