ცოცხალი გაიდლაინები - MDX და სხვა ჩარჩოები

თქვენ შეგიძლიათ გქონდეთ საუკეთესო ღია კოდის პროექტი, მაგრამ თუ მას არ აქვს კარგი დოკუმენტაცია, დიდი შანსია, რომ ის არასოდეს წავა. ოფისში კარგი დოკუმენტაცია ხელს შეგიშლით იმავე კითხვებზე პასუხის გაცემაში. დოკუმენტაცია ასევე უზრუნველყოფს, რომ ადამიანებს შეუძლიათ გაიგონ პროექტი, თუ ძირითადი თანამშრომლები დატოვებენ კომპანიას ან შეიცვლება როლები. ცხოვრების მითითებები ხელს შეუწყობს მონაცემთა მთლიანობის უზრუნველყოფას.

თუ გრძელი ტექსტის დაწერა გჭირდებათ, Markdown არის HTML-ის შესანიშნავი ალტერნატივა. ზოგჯერ Markdown სინტაქსი საკმარისი არ არის. ამ შემთხვევაში ჩვენ შეგვიძლია გამოვიყენოთ HTML მის შიგნით. მაგალითად, მორგებული ელემენტები. ამიტომ, თუ თქვენ აშენებთ დიზაინის სისტემას მშობლიური ვებ კომპონენტებით, ისინი ადვილად შეიძლება იყოს ჩართული ტექსტურ დოკუმენტაციაში. თუ იყენებთ React-ს (ან სხვა JSX ჩარჩოს, როგორიცაა Preact ან Vue), შეგიძლიათ იგივე გააკეთოთ MDX-ით.

ეს სტატია წარმოადგენს დოკუმენტაციის წერისა და სახელმძღვანელოს შექმნის ინსტრუმენტების ფართო მიმოხილვას. აქ ჩამოთვლილი ყველა ინსტრუმენტი არ იყენებს MDX-ს, მაგრამ ის სულ უფრო ხშირად შედის დოკუმენტაციის ინსტრუმენტებში.

რა არის MDX?

ფაილი .mdx აქვს იგივე სინტაქსი, როგორც Markdown, მაგრამ გაძლევთ საშუალებას შემოიტანოთ ინტერაქტიული JSX კომპონენტები და ჩართოთ ისინი თქვენს კონტენტში. Vue კომპონენტების მხარდაჭერა ალფაშია. MDX-თან მუშაობის დასაწყებად, უბრალოდ დააინსტალირეთ „Create React App“. არსებობს პლაგინები Next.js-ისა და Gatsby-სთვის. Docusaurus-ის მომდევნო ვერსიას (ვერსია 2) ასევე ექნება მშობლიური მხარდაჭერა.

დოკუმენტაციის წერა Docusaurus-თან ერთად

დაწერა Docusaurus-მა ფეისბუქზე. ისინი იყენებენ მას ყველა ღია კოდის პროექტზე React-ის გარდა. კომპანიის გარეთ მას იყენებენ Redux, Prettier, Gulp და Babel.

პროექტები, რომლებიც იყენებენ Docusaurus-ს.

Docusaurus შეიძლება გამოყენებულ იქნას დასაწერად ნებისმიერი დოკუმენტაცია, არა მხოლოდ წინა ნაწილის აღსაწერად. მას აქვს React ქუდის ქვეშ, მაგრამ თქვენ არ გჭირდებათ მისი გაცნობა მის გამოსაყენებლად. მას სჭირდება თქვენი Markdown ფაილები, მზად არის რამდენიმე ჯადოსნური და კარგად სტრუქტურირებული, ფორმატირებული და წასაკითხი დოკუმენტაცია ლამაზი დიზაინით.

Redux-ის ვებსაიტზე შეგიძლიათ იხილოთ სტანდარტული Docusaurus შაბლონი

Docusaurus-ით აშენებულ ვებსაიტებს ასევე შეუძლიათ შეიცავდნენ Markdown-ზე დაფუძნებულ ბლოგს. Prism.js დაუყოვნებლივ უკავშირდება სინტაქსის ხაზგასმას. იმისდა მიუხედავად, რომ Docusaurus შედარებით ცოტა ხნის წინ გამოჩნდა, ის StackShare-ზე 2018 წლის საუკეთესო ინსტრუმენტად იქნა აღიარებული.

კონტენტის შექმნის სხვა ვარიანტები

Docusaurus სპეციალურად შექმნილია დოკუმენტაციის შესაქმნელად. რა თქმა უნდა, არსებობს ვებსაიტის შექმნის მილიონი და ერთი გზა - შეგიძლიათ განათავსოთ თქვენი საკუთარი გადაწყვეტა ნებისმიერ ენაზე, CMS-ზე ან გამოიყენოთ სტატიკური საიტის გენერატორი.

მაგალითად, React-ის, IBM-ის დიზაინის სისტემის, Apollo-სა და Ghost CMS-ის დოკუმენტაცია იყენებს Gatsby - სტატიკური საიტის გენერატორს, რომელიც ხშირად გამოიყენება ბლოგებისთვის. თუ Vue-სთან მუშაობთ, მაშინ VuePress თქვენთვის კარგი ვარიანტია. კიდევ ერთი ვარიანტია გამოვიყენოთ პითონში დაწერილი გენერატორი - MkDocs. ის არის ღია წყარო და კონფიგურირებულია ერთი YAML ფაილის გამოყენებით. GitBook ასევე კარგი ვარიანტია, მაგრამ ის უფასოა მხოლოდ საჯარო და არაკომერციული გუნდებისთვის. თქვენ ასევე შეგიძლიათ უბრალოდ ატვირთოთ mardown ფაილები Git-ის გამოყენებით და იმუშაოთ მათთან Github-ში.

დოკუმენტაციის კომპონენტები: Docz, Storybook და Styleguidist

გაიდლაინები, სისტემის დიზაინი, კომპონენტების ბიბლიოთეკები - რასაც არ უნდა უწოდოთ, ის ბოლო დროს ძალიან პოპულარული გახდა. კომპონენტური ჩარჩოების გამოჩენამ, როგორიცაა React და აქ ნახსენები ინსტრუმენტები, გარდაქმნა ისინი ამაო პროექტებიდან სასარგებლო ინსტრუმენტებად.

Storybook, Docz და Styleguidist ყველა ერთსა და იმავეს აკეთებს: აჩვენეთ ინტერაქტიული ელემენტები და დააფიქსირეთ მათი API. პროექტს შეიძლება ჰქონდეს ათობით ან თუნდაც ასობით კომპონენტი - ყველა განსხვავებული მდგომარეობითა და სტილით. თუ გსურთ კომპონენტების ხელახლა გამოყენება, ხალხმა უნდა იცოდეს მათი არსებობა. ამისათვის უბრალოდ ჩამოწერეთ კომპონენტები. გაიდლაინები უზრუნველყოფს თქვენი ყველა კომპონენტის ადვილად საპოვნელ მიმოხილვას. ეს ხელს უწყობს ვიზუალური თანმიმდევრულობის შენარჩუნებას და თავიდან აიცილებს განმეორებით მუშაობას.

ეს ხელსაწყოები იძლევა მოსახერხებელ საშუალებას სხვადასხვა მდგომარეობის სანახავად. შეიძლება რთული იყოს კომპონენტის თითოეული მდგომარეობის რეპროდუცირება რეალური განაცხადის კონტექსტში. რეალურ აპლიკაციაზე დაწკაპუნების ნაცვლად, ღირს ცალკე კომპონენტის შემუშავება. ძნელად მისადგომი მდგომარეობების (როგორიცაა ჩატვირთვის მდგომარეობები) სიმულაცია შესაძლებელია.

სხვადასხვა მდგომარეობის ვიზუალურ დემონსტრირებასთან და თვისებების ჩამონათვალთან ერთად, ხშირად საჭიროა შინაარსის ზოგადი აღწერილობის დაწერა - დიზაინის დასაბუთება, გამოყენების შემთხვევები ან მომხმარებლის ტესტირების შედეგების აღწერა. Markdown-ის სწავლა ძალიან მარტივია - იდეალურ შემთხვევაში, გაიდლაინები უნდა იყოს საერთო რესურსი დიზაინერებისა და დეველოპერებისთვის. Docz, Styleguidist და Storybook გთავაზობთ Markdown-ის კომპონენტებთან მარტივად შერევის საშუალებას.

Docz

ამჟამად 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>

თქვენ შეგიძლიათ შეფუთოთ თქვენი საკუთარი React კომპონენტები <Playground>ჩაშენებული CodePen-ის ან CodeSandbox-ის ანალოგის შესაქმნელად - ანუ თქვენ ხედავთ თქვენს კომპონენტს და შეგიძლიათ მისი რედაქტირება.

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

<Props> აჩვენებს ყველა ხელმისაწვდომ თვისებას მოცემული React კომპონენტისთვის, ნაგულისხმევი მნიშვნელობებისთვის და საჭიროა თუ არა ეს თვისება.

<Props of={Button} />

პირადად მე მიმაჩნია, რომ MDX-ზე დაფუძნებული ეს მიდგომა არის ყველაზე მარტივი გასაგები და ყველაზე მარტივი მუშაობა.

თუ გეტსბის სტატიკური საიტის გენერატორის მოყვარული ხართ, Docz გთავაზობთ შესანიშნავ ინტეგრაციას.

სტილის სახელმძღვანელო

Docz-ის მსგავსად, მაგალითები იწერება Markdown სინტაქსის გამოყენებით. Styleguidist იყენებს Markdown კოდის ბლოკებს (სამმაგი ციტატები) ჩვეულებრივ ფაილებში .md ფაილები და არა MDX.

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

კოდის ბლოკები Markdown-ში ჩვეულებრივ უბრალოდ აჩვენებს კოდს. Styleguidist-ის გამოყენებისას, კოდის ნებისმიერი ბლოკი ენის ტეგით js, jsx ან javascript გადაიცემა როგორც React კომპონენტი. Docz-ის მსგავსად, კოდი რედაქტირებადია - შეგიძლიათ შეცვალოთ თვისებები და მყისიერად ნახოთ შედეგი.

Styleguidist ავტომატურად შექმნის თვისებების ცხრილს PropTypes, Flow ან Typescript დეკლარაციებიდან.

Styleguidist ამჟამად მხარს უჭერს React-სა და Vue-ს.

მოთხრობის წიგნი

Storybook პოზიციონირებს როგორც "UI კომპონენტის განვითარების გარემო". იმის ნაცვლად, რომ ჩაწეროთ კომპონენტების მაგალითი Markdown ან MDX ფაილებში, თქვენ წერთ ისტორიები Javascript ფაილებში. Story დაასაბუთეთ კომპონენტის სპეციფიკური მდგომარეობა. მაგალითად, კომპონენტს შეიძლება ჰქონდეს ჩატვირთული მდგომარეობის და გამორთული მდგომარეობის ისტორიები (ინვალიდები).

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

Storybook ბევრად უფრო რთულია, ვიდრე Styleguidist და Docz. მაგრამ ამავე დროს, ეს არის ყველაზე პოპულარული ვარიანტი; პროექტს აქვს 36-ზე მეტი ვარსკვლავი Github-ზე. ეს არის ღია კოდის პროექტი 000 კონტრიბუტორით და სრულ განაკვეთზე პერსონალით. მას იყენებენ Airbnb, Algolia, Atlassian, Lyft და Salesforce. Storybook მხარს უჭერს მეტ ჩარჩოს, ვიდრე კონკურენტებს - React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte და რეგულარული HTML.

მომავალ გამოშვებაში იქნება ფუნქციები Docz-დან და დაინერგება MDX.

# Button

Some _notes_ about your button written with **markdown syntax**.

<Story name="disabled">
  <Button disabled>lorem ipsum</Button>
</Story>

Storybook-ის ახალი ფუნქციები ეტაპობრივად გამოვა მომდევნო რამდენიმე თვის განმავლობაში და, როგორც ჩანს, ეს იქნება დიდი წინგადადგმული ნაბიჯი.

შედეგები

ნიმუშების ბიბლიოთეკის უპირატესობები გამოიხატება მილიონობით სტატიაში Medium-ზე. როდესაც კარგად აკეთებენ, ისინი აადვილებენ მონათესავე პროდუქტების შექმნას და იდენტურობის შენარჩუნებას. რა თქმა უნდა, არცერთი ეს ინსტრუმენტი არ შექმნის ჯადოსნურ დიზაინს. ეს მოითხოვს ფრთხილად დიზაინს და CSS-ს. მაგრამ როდესაც დადგება დრო, რომ დიზაინის სისტემა ხელმისაწვდომი გახდეს მთელი კომპანიისთვის, Docz, Storybook და Styleguidist შესანიშნავი ვარიანტებია.

მთარგმნელისგან. ეს არის ჩემი პირველი გამოცდილება ჰაბრეზე. თუ აღმოაჩენთ რაიმე უზუსტობას, ან გაქვთ წინადადებები სტატიის გასაუმჯობესებლად, მომწერეთ პირად შეტყობინებაში.

წყარო: www.habr.com