הנחיות חיים - 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) תהיה תמיכה מובנית.

כתיבת תיעוד עם דוקוסאורוס

כתב דוקוסאורוס בפייסבוק. הם משתמשים בו בכל פרויקט קוד פתוח מלבד React. מחוץ לחברה, Redux, Prettier, Gulp ובאבל משתמשים בו.

פרויקטים המשתמשים ב-Docusaurus.

ניתן להשתמש בדוקוסאורוס לכתיבה כל תיעוד, לא רק לתיאור החזית. יש לו React מתחת למכסה המנוע, אבל אתה לא צריך להכיר אותו כדי להשתמש בו. זה לוקח את קבצי Markdown שלך, קורט של קסם ותיעוד מובנה היטב, מעוצב וקריא עם עיצוב יפהפה מוכן.

אתה יכול לראות את תבנית ברירת המחדל של Docusaurus באתר Redux.

אתרים שנבנו עם Docusaurus יכולים לכלול גם בלוג מבוסס Markdown. להדגשת תחביר, Prism.js נכלל מיד. למרות העובדה ש-Docusaurus הופיע לאחרונה יחסית, הוא הוכר ככלי הטוב ביותר של 2018 ב-StackShare.

אפשרויות אחרות ליצירת תוכן

Docusaurus תוכנן במיוחד ליצירת תיעוד. כמובן, יש מיליון ואחת דרכים ליצור אתר אינטרנט - אתה יכול לפרוס פתרון משלך בכל שפה, CMS, או להשתמש במחולל אתרים סטטי.

לדוגמה, התיעוד של React, מערכת העיצוב של IBM, Apollo ו-Ghost CMS משתמשים ב-Gatsby, מחולל אתרים סטטי המשמש לעתים קרובות לבלוגים. אם אתה עובד עם Vue אז VuePress היא אפשרות טובה עבורך. אפשרות נוספת היא להשתמש במחולל שנכתב ב-Python - MkDocs. הוא פתוח ומוגדר עם קובץ YAML יחיד. GitBook היא גם אפשרות טובה, אבל היא חינמית רק לצוותים פתוחים ולא מסחריים. אתה יכול גם פשוט להעלות קבצי Mardown באמצעות git ולעבוד איתם ב- Github.

תיעוד רכיבים: דוק, ספר סיפורים וסטיילגיידיסט

הנחיות, עיצוב מערכת, ספריות רכיבים, איך שלא תרצו לקרוא להם, אלה הפכו פופולריים מאוד לאחרונה. הופעתם של מסגרות רכיבים כמו React והכלים שהוזכרו כאן אפשרה להפוך אותם מפרויקטים של יהירות לכלים שימושיים.

Storybook, Docz ו- Styleguidist עושים את אותו הדבר: מציגים אלמנטים אינטראקטיביים ומתעדים את ה-API שלהם. פרויקט יכול לכלול עשרות ואף מאות רכיבים, כולם עם מצבים וסגנונות שונים. אם אתה רוצה לעשות שימוש חוזר ברכיבים, אנשים צריכים לדעת שהם קיימים. כדי לעשות זאת, זה מספיק כדי לקטלג את הרכיבים. הנחיות מספקות סקירה קלה לחיפוש של כל הרכיבים שלך. זה עוזר לשמור על עקביות ויזואלית ולהימנע מעבודה חוזרת ונשנית.

כלים אלה מספקים דרך נוחה להציג מצבים שונים. זה יכול להיות קשה לשכפל כל מצב של רכיב בהקשר של יישום אמיתי. במקום ללחוץ על האפליקציה בפועל, כדאי לפתח רכיב נפרד. אפשר לדגמן מצבים שקשה להגיע אליהם (לדוגמה, מצב טעינה).

לצד הדגמה ויזואלית של מצבים שונים ורשימת מאפיינים, לרוב יש צורך לכתוב תיאור כללי של התוכן – נימוקים עיצוביים, מקרי שימוש או תיאור תוצאות בדיקות המשתמש. קל מאוד ללמוד את Markdown - באופן אידיאלי, הנחיות צריכות להיות משאב משותף עבור מעצבים ומפתחים. Docz, Styleguidist ו-Storybook מציעים דרך לערבב בקלות את Markdown עם רכיבים.

דוצ'

נכון לעכשיו, Docz עובד רק עם React, אך עובד באופן פעיל על תמיכה ברכיבי Preact, Vue ו-web. Docz הוא העדכני ביותר מבין שלושת הכלים, אך הצליח לאסוף למעלה מ-14 כוכבים ב-Github. דוק מציג שני מרכיבים - <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 מחייב את עצמו כ"סביבת פיתוח רכיבי ממשק משתמש". במקום לכתוב דוגמאות רכיבים בתוך קבצי Markdown או MDX, אתה כותב היסטוריה בתוך קבצי Javascript. כתבה לתעד את המצב הספציפי של רכיב. לדוגמה, לרכיב עשויות להיות היסטוריות עבור מצב טעינה ומצב מושבת (נכה).

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

ספר סיפורים מורכב הרבה יותר מ- Styleguidist ו-Docz. אבל יחד עם זאת, זו האופציה הפופולרית ביותר, ב-Github לפרויקט יש יותר מ-36 כוכבים. זהו פרויקט קוד פתוח עם 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 הן אפשרויות מצוינות.

מאת מתרגם. זו ההתנסות הראשונה שלי ב-Habré. אם אתם מוצאים אי דיוקים, או שיש לכם הצעות לשיפור המאמר - כתבו בהודעה אישית.

מקור: www.habr.com