ప్రత్యక్ష మార్గదర్శకాలు - MDX మరియు ఇతర ఫ్రేమ్‌వర్క్‌లు

మీరు ఉత్తమ ఓపెన్ సోర్స్ ప్రాజెక్ట్‌ను కలిగి ఉండవచ్చు, కానీ దానికి మంచి డాక్యుమెంటేషన్ లేకపోతే, అది ఎప్పటికీ టేకాఫ్ చేయబడదు. కార్యాలయంలో, మంచి డాక్యుమెంటేషన్ అదే ప్రశ్నలకు సమాధానం ఇవ్వకుండా మిమ్మల్ని నిరోధిస్తుంది. కీలక ఉద్యోగులు కంపెనీని విడిచిపెట్టినట్లయితే లేదా పాత్రలు మారితే ప్రజలు ప్రాజెక్ట్‌ను అర్థం చేసుకోగలరని డాక్యుమెంటేషన్ నిర్ధారిస్తుంది. జీవన మార్గదర్శకాలు డేటా సమగ్రతను నిర్ధారించడంలో సహాయపడతాయి.

మీరు పొడవైన వచనాన్ని వ్రాయవలసి వస్తే, మార్క్‌డౌన్ HTMLకి గొప్ప ప్రత్యామ్నాయం. కొన్నిసార్లు మార్క్‌డౌన్ సింటాక్స్ సరిపోదు. ఈ సందర్భంలో మనం దాని లోపల HTMLని ఉపయోగించవచ్చు. ఉదాహరణకు, అనుకూల అంశాలు. అందువల్ల, మీరు స్థానిక వెబ్ భాగాలతో డిజైన్ సిస్టమ్‌ను నిర్మిస్తుంటే, వాటిని సులభంగా టెక్స్ట్ డాక్యుమెంటేషన్‌లో చేర్చవచ్చు. మీరు React (లేదా Preact లేదా Vue వంటి ఏదైనా ఇతర JSX ఫ్రేమ్‌వర్క్‌ని) ఉపయోగిస్తుంటే, మీరు MDXతో కూడా అదే పనిని చేయవచ్చు.

ఈ కథనం డాక్యుమెంటేషన్ రాయడం మరియు మార్గదర్శకాలను రూపొందించడం కోసం సాధనాల యొక్క విస్తృత అవలోకనం. ఇక్కడ జాబితా చేయబడిన అన్ని సాధనాలు MDXని ఉపయోగించవు, కానీ ఇది డాక్యుమెంటేషన్ సాధనాల్లో ఎక్కువగా చేర్చబడుతోంది.

MDX అంటే ఏమిటి?

ఫైలు .mdx మార్క్‌డౌన్ వలె అదే వాక్యనిర్మాణాన్ని కలిగి ఉంది, కానీ ఇంటరాక్టివ్ JSX భాగాలను దిగుమతి చేసుకోవడానికి మరియు వాటిని మీ కంటెంట్‌లో పొందుపరచడానికి మిమ్మల్ని అనుమతిస్తుంది. Vue భాగాలకు మద్దతు ఆల్ఫాలో ఉంది. MDXతో పని చేయడం ప్రారంభించడానికి, “రియాక్ట్ యాప్‌ని సృష్టించు”ని ఇన్‌స్టాల్ చేయండి. Next.js మరియు Gatsby కోసం ప్లగిన్‌లు ఉన్నాయి. Docusaurus యొక్క తదుపరి వెర్షన్ (వెర్షన్ 2)కి కూడా స్థానిక మద్దతు ఉంటుంది.

డాక్యుసారస్‌తో డాక్యుమెంటేషన్ రాయడం

Docusaurus Facebookలో రాశారు. వారు రియాక్ట్ మినహా ప్రతి ఓపెన్ సోర్స్ ప్రాజెక్ట్‌లో దీనిని ఉపయోగిస్తారు. కంపెనీ వెలుపల దీనిని Redux, Prettier, Gulp మరియు Babel ఉపయోగిస్తున్నారు.

Docusaurus ఉపయోగించే ప్రాజెక్ట్‌లు.

డాక్యుసారస్ రాయడానికి ఉపయోగించవచ్చు ఏ డాక్యుమెంటేషన్, ఫ్రంటెండ్‌ను వివరించడానికి మాత్రమే కాదు. ఇది హుడ్ కింద రియాక్ట్‌ని కలిగి ఉంది, కానీ దాన్ని ఉపయోగించడానికి మీకు దాని గురించి తెలిసి ఉండవలసిన అవసరం లేదు. ఇది మీ మార్క్‌డౌన్ ఫైల్‌లను తీసుకుంటుంది, చిటికెడు మేజిక్ మరియు చక్కగా నిర్మాణాత్మకమైన, ఫార్మాట్ చేయబడిన మరియు అందమైన డిజైన్‌తో చదవగలిగే డాక్యుమెంటేషన్ సిద్ధంగా ఉంది.

Redux వెబ్‌సైట్‌లో మీరు ప్రామాణిక Docusaurus టెంప్లేట్‌ను చూడవచ్చు

Docusaurusతో రూపొందించబడిన వెబ్‌సైట్‌లు మార్క్‌డౌన్ ఆధారిత బ్లాగును కూడా కలిగి ఉంటాయి. సింటాక్స్ హైలైటింగ్ కోసం Prism.js వెంటనే కనెక్ట్ చేయబడింది. Docusaurus సాపేక్షంగా ఇటీవల కనిపించినప్పటికీ, ఇది StackShareలో 2018 యొక్క ఉత్తమ సాధనంగా గుర్తించబడింది.

ఇతర కంటెంట్ సృష్టి ఎంపికలు

డాక్యుమెంటేషన్ సృష్టించడం కోసం డాక్యుసారస్ ప్రత్యేకంగా రూపొందించబడింది. వాస్తవానికి, వెబ్‌సైట్‌ను రూపొందించడానికి మిలియన్ మరియు ఒక మార్గాలు ఉన్నాయి - మీరు మీ స్వంత పరిష్కారాన్ని ఏ భాషలోనైనా ఉపయోగించవచ్చు, CMS లేదా స్టాటిక్ సైట్ జనరేటర్‌ని ఉపయోగించవచ్చు.

ఉదాహరణకు, రియాక్ట్, IBM డిజైన్ సిస్టమ్, అపోలో మరియు ఘోస్ట్ CMS కోసం డాక్యుమెంటేషన్ Gatsbyని ఉపయోగిస్తాయి - ఇది బ్లాగ్‌ల కోసం తరచుగా ఉపయోగించే స్టాటిక్ సైట్ జనరేటర్. మీరు Vueతో పని చేస్తే, VuePress మీకు మంచి ఎంపిక. పైథాన్ - 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 వలె, ఉదాహరణలు మార్క్‌డౌన్ సింటాక్స్ ఉపయోగించి వ్రాయబడతాయి. Styleguidist సాధారణ ఫైల్‌లలో మార్క్‌డౌన్ కోడ్ బ్లాక్‌లను (ట్రిపుల్ కోట్స్) ఉపయోగిస్తుంది .md ఫైల్‌లు, MDX కాదు.

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

మార్క్‌డౌన్‌లోని కోడ్ బ్లాక్‌లు సాధారణంగా కోడ్‌ని చూపుతాయి. స్టైల్‌గైడిస్ట్‌ని ఉపయోగిస్తున్నప్పుడు, భాష ట్యాగ్‌తో కూడిన ఏదైనా బ్లాక్ కోడ్ js, jsx లేదా javascript రియాక్ట్ కాంపోనెంట్‌గా రెండర్ చేస్తుంది. Docz వలె, కోడ్ సవరించదగినది - మీరు లక్షణాలను మార్చవచ్చు మరియు తక్షణమే ఫలితాన్ని చూడవచ్చు.

PropTypes, Flow లేదా Typescript డిక్లరేషన్‌ల నుండి Styleguidist స్వయంచాలకంగా ఆస్తి పట్టికను సృష్టిస్తుంది.

Styleguidist ప్రస్తుతం React మరియు Vueకి మద్దతు ఇస్తుంది.

స్టోరీబుక్

స్టోరీబుక్ తనను తాను "UI కాంపోనెంట్ డెవలప్‌మెంట్ ఎన్విరాన్‌మెంట్"గా ఉంచుతుంది. మార్క్‌డౌన్ లేదా MDX ఫైల్‌లలోని ఉదాహరణ భాగాలను వ్రాయడానికి బదులుగా, మీరు వ్రాస్తారు చరిత్రలో Javascript ఫైల్స్ లోపల. కథ ఒక భాగం యొక్క నిర్దిష్ట స్థితిని డాక్యుమెంట్ చేయండి. ఉదాహరణకు, ఒక భాగం లోడ్ చేయబడిన స్థితి మరియు డిసేబుల్ స్థితికి సంబంధించిన చరిత్రలను కలిగి ఉండవచ్చు (వికలాంగ).

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

స్టోరీబుక్ Styleguidist మరియు Docz కంటే చాలా క్లిష్టమైనది. కానీ అదే సమయంలో, ఇది అత్యంత ప్రజాదరణ పొందిన ఎంపిక; ప్రాజెక్ట్ Githubలో 36 కంటే ఎక్కువ నక్షత్రాలను కలిగి ఉంది. ఇది 000 మంది కంట్రిబ్యూటర్లు మరియు పూర్తి-సమయ సిబ్బందితో ఓపెన్ సోర్స్ ప్రాజెక్ట్. దీనిని Airbnb, అల్గోలియా, అట్లాసియన్, లిఫ్ట్ మరియు సేల్స్‌ఫోర్స్ ఉపయోగిస్తాయి. స్టోరీబుక్ పోటీదారుల కంటే ఎక్కువ ఫ్రేమ్‌వర్క్‌లకు మద్దతు ఇస్తుంది - రియాక్ట్, రియాక్ట్ నేటివ్, వ్యూ, కోణీయ, మిత్రిల్, ఎంబర్, రియోట్, స్వెల్ట్ మరియు సాధారణ 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