வாழ்க்கை வழிகாட்டுதல்கள் - MDX மற்றும் பிற கட்டமைப்புகள்

உங்களிடம் சிறந்த ஓப்பன் சோர்ஸ் திட்டம் இருக்கலாம், ஆனால் அதற்கு நல்ல ஆவணங்கள் இல்லையென்றால், அது ஒருபோதும் செயல்படாது. அலுவலகத்தில், நல்ல ஆவணங்கள் ஒரே கேள்விகளுக்கு மீண்டும் மீண்டும் பதிலளிப்பதைத் தடுக்கும். முக்கிய ஊழியர்கள் நிறுவனத்தை விட்டு வெளியேறினால் அல்லது பாத்திரங்கள் மாறினால், மக்கள் திட்டத்தைப் பற்றி உணர முடியும் என்பதை ஆவணப்படுத்துதல் உறுதி செய்கிறது. நேரடி வழிகாட்டுதல்கள் தரவு ஒருமைப்பாட்டை உறுதிப்படுத்த உதவுகின்றன.

நீங்கள் நீண்ட உரை எழுத வேண்டும் என்றால், மார்க் டவுன் HTML க்கு ஒரு சிறந்த மாற்றாகும். சில நேரங்களில் மார்க் டவுன் தொடரியல் போதாது. இந்த வழக்கில், நாம் அதன் உள்ளே HTML ஐப் பயன்படுத்தலாம். எடுத்துக்காட்டாக, தனிப்பயன் கூறுகள். எனவே, நீங்கள் சொந்த வலை கூறுகளுடன் ஒரு வடிவமைப்பு அமைப்பை உருவாக்குகிறீர்கள் என்றால், அவற்றை உரை ஆவணத்தில் சேர்ப்பது எளிது. நீங்கள் React (அல்லது Preact அல்லது Vue போன்ற பிற JSX கட்டமைப்பை) பயன்படுத்துகிறீர்கள் என்றால், MDX உடன் அதையே செய்யலாம்.

இந்தக் கட்டுரை ஆவணங்களை எழுதுவதற்கும் வழிகாட்டுதலை உருவாக்குவதற்குமான கருவிகளின் விரிவான கண்ணோட்டமாகும். இங்கே பட்டியலிடப்பட்டுள்ள அனைத்து கருவிகளும் MDX ஐப் பயன்படுத்துவதில்லை, ஆனால் இது ஆவணமாக்கல் கருவிகளில் அதிகளவில் சேர்க்கப்படுகிறது.

MDX என்றால் என்ன?

கோப்பு .mdx Markdown போன்ற தொடரியல் உள்ளது, ஆனால் ஊடாடும் JSX கூறுகளை இறக்குமதி செய்து அவற்றை உங்கள் உள்ளடக்கத்தில் உட்பொதிக்க உங்களை அனுமதிக்கிறது. Vue கூறுகளுக்கான ஆதரவு ஆல்பாவில் உள்ளது. MDX உடன் பணிபுரியத் தொடங்க, "ரியாக்ட் ஆப்ஸை உருவாக்கு" என்பதை நிறுவவும். Next.js மற்றும் Gatsbyக்கான செருகுநிரல்கள் உள்ளன. Docusaurus இன் அடுத்த பதிப்பு (பதிப்பு 2) உள்ளமைக்கப்பட்ட ஆதரவையும் கொண்டிருக்கும்.

Docusaurus உடன் ஆவணங்களை எழுதுதல்

Docusaurus Facebook இல் எழுதினார். ரியாக்ட் தவிர ஒவ்வொரு திறந்த மூல திட்டத்திலும் அவர்கள் அதைப் பயன்படுத்துகிறார்கள். நிறுவனத்திற்கு வெளியே, Redux, Prettier, Gulp மற்றும் Babel இதைப் பயன்படுத்துகின்றனர்.

Docusaurus ஐப் பயன்படுத்தும் திட்டங்கள்.

Docusaurusஐ எழுத பயன்படுத்தலாம் любой ஆவணங்கள், முன்பக்கத்தை விவரிப்பதற்கு மட்டுமல்ல. இது ஹூட்டின் கீழ் ரியாக்ட் உள்ளது, ஆனால் அதைப் பயன்படுத்த நீங்கள் அதை நன்கு அறிந்திருக்க வேண்டியதில்லை. இது உங்கள் மார்க் டவுன் கோப்புகளை எடுக்கும், ஒரு சிட்டிகை மேஜிக் மற்றும் நன்கு கட்டமைக்கப்பட்ட, வடிவமைக்கப்பட்ட மற்றும் அழகான வடிவமைப்புடன் படிக்கக்கூடிய ஆவணங்கள் தயாராக உள்ளது.

Redux இணையதளத்தில் இயல்புநிலை Docusaurus டெம்ப்ளேட்டை நீங்கள் பார்க்கலாம்.

Docusaurus உடன் கட்டமைக்கப்பட்ட தளங்களில் Markdown-அடிப்படையிலான வலைப்பதிவும் இருக்கலாம். தொடரியல் சிறப்பம்சமாக, Prism.js உடனடியாக சேர்க்கப்படும். Docusaurus ஒப்பீட்டளவில் சமீபத்தில் தோன்றிய போதிலும், இது StackShare இல் 2018 இன் சிறந்த கருவியாக அங்கீகரிக்கப்பட்டது.

பிற உள்ளடக்க உருவாக்க விருப்பங்கள்

Docusaurus குறிப்பாக ஆவணங்களை உருவாக்க வடிவமைக்கப்பட்டுள்ளது. நிச்சயமாக, ஒரு வலைத்தளத்தை உருவாக்க ஒரு மில்லியன் மற்றும் ஒரு வழிகள் உள்ளன - நீங்கள் எந்த மொழியிலும், CMS இல் உங்கள் சொந்த தீர்வை வரிசைப்படுத்தலாம் அல்லது நிலையான தள ஜெனரேட்டரைப் பயன்படுத்தலாம்.

எடுத்துக்காட்டாக, ரியாக்ட், ஐபிஎம் டிசைன் சிஸ்டம், அப்பல்லோ மற்றும் கோஸ்ட் சிஎம்எஸ் ஆகியவற்றிற்கான ஆவணங்கள் கேட்ஸ்பையைப் பயன்படுத்துகின்றன, இது பெரும்பாலும் வலைப்பதிவுகளுக்குப் பயன்படுத்தப்படும் நிலையான தள ஜெனரேட்டராகும். நீங்கள் Vue உடன் பணிபுரிகிறீர்கள் என்றால் VuePress உங்களுக்கு ஒரு நல்ல வழி. Python - MkDocs இல் எழுதப்பட்ட ஜெனரேட்டரைப் பயன்படுத்துவது மற்றொரு விருப்பம். இது ஒரு YAML கோப்புடன் திறக்கப்பட்டு கட்டமைக்கப்பட்டுள்ளது. GitBook ஒரு நல்ல வழி, ஆனால் இது திறந்த மற்றும் வணிகம் அல்லாத குழுக்களுக்கு மட்டுமே இலவசம். நீங்கள் git ஐப் பயன்படுத்தி மார்டவுன் கோப்புகளைப் பதிவேற்றலாம் மற்றும் Github இல் வேலை செய்யலாம்.

கூறு ஆவணப்படுத்தல்: Docz, Storybook மற்றும் Styleguidist

வழிகாட்டுதல்கள், சிஸ்டம் டிசைன், கூறு நூலகங்கள் என எதை வேண்டுமானாலும் அழைக்கலாம், இவை சமீபத்தில் மிகவும் பிரபலமாகி வருகின்றன. ரியாக்ட் மற்றும் இங்கு குறிப்பிடப்பட்டுள்ள கருவிகள் போன்ற கூறு கட்டமைப்புகளின் தோற்றம், அவற்றை வேனிட்டி திட்டங்களிலிருந்து பயனுள்ள கருவிகளாக மாற்றுவதை சாத்தியமாக்கியுள்ளது.

Storybook, Docz மற்றும் Styleguidist ஆகியவை இதையே செய்கின்றன: ஊடாடும் கூறுகளைக் காட்டி அவற்றின் APIயை ஆவணப்படுத்தவும். ஒரு திட்டத்தில் டஜன் கணக்கான அல்லது நூற்றுக்கணக்கான கூறுகள் இருக்கலாம், அனைத்தும் வெவ்வேறு நிலைகள் மற்றும் பாணிகளுடன். நீங்கள் கூறுகளை மீண்டும் பயன்படுத்த விரும்பினால், அவை இருப்பதை மக்கள் அறிந்து கொள்ள வேண்டும். இதைச் செய்ய, கூறுகளை பட்டியலிட்டால் போதும். வழிகாட்டுதல்கள் உங்கள் அனைத்து கூறுகளையும் எளிதாகத் தேடக்கூடிய கண்ணோட்டத்தை வழங்குகின்றன. இது காட்சி நிலைத்தன்மையை பராமரிக்கவும், மீண்டும் மீண்டும் வேலை செய்வதைத் தவிர்க்கவும் உதவுகிறது.

இந்த கருவிகள் பல்வேறு மாநிலங்களைப் பார்க்க வசதியான வழியை வழங்குகின்றன. உண்மையான பயன்பாட்டின் சூழலில் ஒரு கூறுகளின் ஒவ்வொரு நிலையையும் பிரதிபலிக்க கடினமாக இருக்கலாம். உண்மையான பயன்பாட்டைக் கிளிக் செய்வதற்குப் பதிலாக, ஒரு தனி கூறுகளை உருவாக்குவது மதிப்பு. அடைய முடியாத நிலைகளை மாதிரியாக்குவது சாத்தியம் (உதாரணமாக, ஏற்றுதல் நிலை).

பல்வேறு நிலைகளின் காட்சி ஆர்ப்பாட்டம் மற்றும் பண்புகளின் பட்டியல் ஆகியவற்றுடன், உள்ளடக்கத்தின் பொதுவான விளக்கத்தை எழுதுவது அவசியம் - வடிவமைப்பு பகுத்தறிவுகள், பயன்பாட்டு வழக்குகள் அல்லது பயனர் சோதனை முடிவுகளின் விளக்கம். மார்க் டவுன் கற்றுக்கொள்வது மிகவும் எளிதானது - வழிகாட்டுதல்கள் வடிவமைப்பாளர்கள் மற்றும் டெவலப்பர்களுக்கான பகிரப்பட்ட ஆதாரமாக இருக்க வேண்டும். Docz, Styleguidist மற்றும் Storybook ஆகியவை மார்க் டவுனைக் கூறுகளுடன் எளிதாகக் கலக்க ஒரு வழியை வழங்குகின்றன.

டாக்ஸ்

தற்போது, ​​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-அடிப்படையிலான அணுகுமுறையைப் புரிந்துகொள்வதற்கு எளிதானது மற்றும் வேலை செய்வதற்கு எளிதானது.

நீங்கள் கேட்ஸ்பியின் நிலையான தள ஜெனரேட்டரின் ரசிகராக இருந்தால், Docz சிறந்த ஒருங்கிணைப்புகளை வழங்குகிறது.

பாணி வழிகாட்டி

Docz இல் உள்ளதைப் போலவே, Markdown தொடரியல் பயன்படுத்தி உதாரணங்கள் எழுதப்படுகின்றன. Styleguidist வழக்கமான கோப்புகளில் மார்க் டவுன் குறியீடு தொகுதிகளை (டிரிபிள் மேற்கோள்கள்) பயன்படுத்துகிறது .md கோப்புகள், MDX இல் இல்லை.

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

மார்க் டவுனில் உள்ள குறியீடு தொகுதிகள் பொதுவாக குறியீட்டைக் காட்டுகின்றன. Styleguidist ஐப் பயன்படுத்தும் போது, ​​மொழிக் குறிச்சொல்லுடன் கூடிய குறியீட்டின் எந்தத் தொகுதியும் js, jsx அல்லது javascript எதிர்வினை கூறுகளாக வழங்குவார்கள். Docz ஐப் போலவே, குறியீடு திருத்தக்கூடியது - நீங்கள் பண்புகளை மாற்றலாம் மற்றும் முடிவை உடனடியாகக் காணலாம்.

Styleguidist தானாகவே PropTypes, Flow அல்லது Typescript declarations மூலம் சொத்துத் தாளை உருவாக்குவார்.

Styleguidist இப்போது React மற்றும் Vue ஐ ஆதரிக்கிறது.

கதைப்புத்தகம்

ஸ்டோரிபுக் தன்னை ஒரு "UI கூறு மேம்பாட்டு சூழல்" என்று கூறுகிறது. மார்க் டவுன் அல்லது MDX கோப்புகளுக்குள் கூறு உதாரணங்களை எழுதுவதற்குப் பதிலாக, நீங்கள் எழுதுகிறீர்கள் வரலாறு ஜாவாஸ்கிரிப்ட் கோப்புகளுக்குள். கதை ஒரு கூறுகளின் குறிப்பிட்ட நிலையை ஆவணப்படுத்துகிறது. எடுத்துக்காட்டாக, ஒரு கூறு ஏற்றுதல் நிலை மற்றும் முடக்கப்பட்ட நிலைக்கான வரலாறுகளைக் கொண்டிருக்கலாம் (ஊனமுற்றோர்).

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

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 சிறந்த விருப்பங்கள்.

மொழிபெயர்ப்பாளரிடமிருந்து. ஹப்ரேயில் இது எனது முதல் அனுபவம். ஏதேனும் தவறுகள் இருந்தால், அல்லது கட்டுரையை மேம்படுத்துவதற்கான பரிந்துரைகள் இருந்தால் - தனிப்பட்ட முறையில் எழுதுங்கள்.

ஆதாரம்: www.habr.com