דוקוסאורוס: כיצד ליצור תיעוד טכני מקצועי

אם יש לכם ספריית קוד, מסגרת או מוצר SaaS בידיים, סביר להניח ששמתם לב לכך לארגן את המידע עבור משתמשים, זהו כאב ראש אמיתי. אין צורך לבזבז שבועות על תכנות מערכת מאפס או להתמודד עם מערכת ניהול תוכן מסורבלת כאשר קיימים כלים שתוכננו במיוחד לכך. כאן נכנס לתמונה [הכלי/אפליקציה/מכשיר]. דוקוסאורוס, פנינה בקוד פתוח שנוצרה על ידי צוות פייסבוק והופכת את רשימות Markdown שלכם לאתר אינטרנט מקצועי כהרף עין.

מה שהופך את הכלי הזה לכל כך מושך הוא שהוא לא רק יורק טקסט על המסך; זה... מחולל אתרים סטטי (SSG) הוא משתמש ב-React, מה שאומר שאתם מקבלים את המהירות של אתר סטטי אבל עם כל העוצמה של אפליקציה מודרנית. זה אידיאלי עבור אלו המחפשים משהו קל משקל, מאובטח, ומעל הכל, קל מאוד לתחזוקה ללא הטרחה של מסדי נתונים מורכבים.

מהו בעצם דוקוסאורוס ואיך הוא עובד?

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

עם הזמן, הכלי התפתח. הגרסה הראשונה התמקדה ביצירת אתרים סטטיים מסורתיים, יציבים מאוד ותואמים אפילו לדפדפנים ישנים יותר. עם זאת, גרסה 2 וגרסה 3 הנוכחית עשו קפיצת מדרגה איכותית על ידי יישום הפילוסופיה. ג'אמסטקכעת, הודות לשימוש ב-MDX, ​​ניתן לשלב את הפשטות של Markdown עם רכיבי React, מה שמאפשר לדפים שלכם להכיל אלמנטים אינטראקטיביים שקובץ טקסט רגיל לעולם לא יוכל להציע.

התקנה והפעלה של הפרויקט

כדי להתחיל לתת לגיטימציה לפרויקט שלך, הדבר הראשון שאתה צריך הוא להתקין Node.js (גרסה 16.14 ומעלה)(למרות שגרסה 20+ מומלצת עבור גרסה 3). לאחר שהסביבה מוכנה, אינך צריך להגדיר כל תיקייה בנפרד; תוכל להפעיל את הפקודה npx create-docusaurus@latest my-docs classic להקים את המבנה הבסיסי.

מאמר קשור:

כיצד להוסיף מנוע חיפוש ל-Docusaurus ולמטב את התיעוד שלך

הפריסט שנקרא "קלאסי" הוא המומלץ ביותר מכיוון שהוא כבר מאפשר לך הערכה המלאהתוסף התיעוד, מודול הבלוג ועיצוב ויזואלי מגובש. כדי לראות את התקדמות העבודה שלך בזמן אמת, פשוט הפעל npm startפעולה זו תגדיר שרת מקומי. אם אתה מוכן להעלות אותו לרשת, הפקודה npm run build זה ייצור תיקייה עם קבצי HTML, CSS ו-JS מוכנים לכל שרת.

הבנת מבנה הקבצים

כשתפתחו את הפרויקט שלכם, תראו שהכל מאורגן היטב כך שלא תלכו לאיבוד. התיקייה /docs הוא הלב של האתר, שם יימצאו כל קבצי Markdown שלך. אם ברצונך להוסיף חדשות או עדכונים, תיקיית /blog היא המקום בשבילך. מצד שני, אם עליך ליצור דפים ייחודיים, כגון מדור "צור קשר" או דף נחיתה, עליך לעבור אל /src/pages.

ישנם שני קבצים שעליכם לשים לב אליהם במיוחד. הראשון הוא docusaurus.config.jsשהוא בעצם המוח של הפרויקט; מכאן משנים את כותרת האתר, הצבעים, תפריט הניווט והכותרת התחתונה. השני הוא sidebars.js, היכן שאתה מגדיר סדר המסמכים בסרגל הצד, באופן ידני או על ידי מתן אפשרות למערכת ליצור אותם באופן אוטומטי בהתבסס על מבנה התיקיות שלך.

כוחו של MDX ויצירת תוכן

כתיבה על דוקוסאורוס היא תענוג כי היא תומכת MDX גרסה 3משמעות הדבר היא שתוכלו לכתוב את המדריך שלכם באמצעות תחביר Markdown סטנדרטי ולאחר מכן להוסיף פתאום רכיב React כדי להציג התראה, תרשים אינטראקטיבי או דיאגרמת Mermaid. כדי שהדיאגרמות יעבדו, עליכם רק להפעיל את התוסף המתאים בקובץ התצורה שלכם.

כל מסמך מתחיל ב- חומר חזיתזהו בלוק המטא-דאטה בתחילת הקובץ שבו מגדירים את מזהה הדף, הכותרת והמיקום בסרגל הצד. מבנה זה מאפשר ל-Docusaurus לנהל כתובות URL בצורה חכמה, וליצור נתיבים נקיים כמו tudominio.com/docs/guia-inicio מבלי שתצטרך להגדיר מסלולים באופן ידני.

התאמה אישית חזותית וחוויית משתמש

אם אינך מרוצה מעיצוב ברירת המחדל, ישנן מספר דרכים להתאים אותו אישית. הדרך הקלה ביותר היא לערוך את הקובץ. custom.cssדוקוסאורוס משתמש במסגרת CSS אֵינְסוֹףלכן, ניתן לשנות את משתני הצבע העיקריים או את גודל הגופן מבלי לפגוע בעיצוב הכללי.

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

האתגר של תיעוד API

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

כדי לפתור זאת, ישנן שתי גישות. הראשונה היא להשתמש בתוספים של צד שלישי או לשלב כלים כמו Redoc או Stoplight Elements. הגישה השנייה, ואולי היעילה ביותר עבור צוותים גדולים, היא לשלב את Docusaurus עם כלים ייעודיים כמו אפידוגכלים אלה מאפשרים לך לייבא מפרטי OpenAPI או Swagger וליצור באופן אוטומטי תיעוד טכני, שניתן לשלב אותו בצורה חלקה עם המערכת האקולוגית של Docusaurus כדי לספק חוויית מפתח מלאה.

חיפוש, ניהול גרסאות ופריסה סופית

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

מאפיין מרכזי נוסף הוא ה- ניהול גרסאות מסמכיםאם אתם משחררים את גרסה 2.0 של התוכנה שלכם אך רוצים שהמשתמשים ימשיכו להתייעץ עם המדריך 1.0, Docusaurus יוצר תמונת מצב של המסמכים שלכם בתיקייה בשם versioned_docs/מאפשר ניווט בין מצבי מוצר שונים.

כשמדובר בפרסום, יש לכם מגוון עצום של אפשרויות. מכיוון שזהו אתר סטטי, תוכלו להשתמש דפי Vercel, Netlify, GitHub או אפילו אירוח ייעודי כמו Kinsta. אתם רק צריכים לחבר את מאגר ה-Git שלכם ולציין את פקודת ה-build. npm run build ולהגדיר את תיקיית הפלט כ build.

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

דניאל טרסה

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