Nextra מאפשרת לך לבנות אתר בתוך דקות, כך שהוא מושלם להפצת מסמכים לצוות שלך.

אם אתה מכיר את Next.js, אתה יכול להשתמש בו כדי לפתח אתר תיעוד בקלות. המסגרת של נקסטרה דואגת עבורך לכל העניין; כל מה שאתה צריך לעשות הוא להוסיף תוכן Markdown או HTML ונתוני YAML או JSON.

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

דרישות לבניית אתר דוק עם Nextra

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

מלבד Node.js, תצטרך להתקין Git. אתה צריך Git כדי לפרוס את האתר לדפי GitHub, Netlify או ספק אירוח אחר. תצטרך גם עורך קוד מתקדם, כגון VS Code.

התקנת Nextra

אתה יכול להשתמש ב- a תבנית Nextra docs לאתחל אתר תיעוד. הפעל שורת פקודה ונווט אל הספרייה שבה ברצונך להגדיר את הפרויקט שלך. לאחר מכן הפעל את הפקודה הבאה כדי לאתחל את אתר התיעוד:

שיבוט git https://github.com/shuding/nextra-docs-template
instagram viewer

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

cd nextra-docs-template
npm להתקין

לאחר סיום ההתקנה, הפעל את היישום. עשה זאת על ידי הפעלת הפקודה הבאה בטרמינל שלך:

npm run dev

פקודה זו מפעילה שרת פיתוח ב-localhost: 3000. עקוב אחר הקישור בטרמינל שלך כדי לצפות באתר התיעוד. דף הבית אמור להיראות כך:

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

כדי להבין כיצד דפים אלה עובדים, תצטרך להבין תחילה כיצד Next.js מעבד דפים.

הבנת מבנה המדריך

מכיוון ש-Nextra משתמש במסגרת Next.js, היא מעבדת כל קובץ ב- דפים/ תיקייה כעמוד נפרד.

בתוך ה דפים בספרייה, תמצא ארבעה קובצי תבניות: about.mdx, advanced.mdx, another.mdx, ו index.mdx. כל אחד מהקבצים הללו מתאים לדף באתר; לדוגמה, index.mdx מתאים לדף הבית. כתובת האתר מארח מקומי: 3000/בערך מתאים ל about.mdx, וכולי.

בְּתוֹך דפים, יש גם תיקיה בשם מִתקַדֵם, מכיל קובץ בודד בשם satori.mdx. כתובת האתר של קובץ זה תהיה localhost: 3000/advanced/satori.

שימו לב כיצד כל אחד מהקבצים הללו מסתיים ב-a .mdx סיומת.

מה זה MDX?

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

MDX טוען, מנתח ומציג JSX במסמך Markdown. הודות ל-MDX, ​​אתה יכול לכתוב רכיבי React ולייבא אותם למסמכי Markdown שלך בעת הצורך. קובצי MDX מסתיימים בסיומת .mdx ויכולים לכלול גם Markdown וגם JSX.

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

כיצד לערוך דפים קיימים באתר התיעוד

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

לדוגמה, פתח את index.mdx קובץ והחלף את התוכן בזה:

# ברוכים הבאים לתיעוד שלי
אני שמח לראות אותך כאן. תודה
## החברתיים שלי
עקבו אחרי ב-[טוויטר](https://twitter.com/kingchuuks) ו-[לינקדאין](https://linkedin.com/in/kingchuks)

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

שמור את הקובץ ובקר בדף הבית של אתר התיעוד שלך. כעת העמוד אמור להיראות כך:

בתחתית העמוד תוכלו למצוא גם את תאריך העדכון האחרון של המסמך.

הוספת דף חדש

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

במקרה זה, צור דף עצמאי ברמה העליונה. פתח קובץ בשם installation.mdx בעורך הקוד שלך והדבק בו את קוד ה-Markdown הבא:

# מדריך התקנה
עקוב אחר המדריך הזה כדי להתקין את החבילה שלי בפרויקט שלך
## 1. התקן את Node.js
כדי להתקין את Node.js, בקר ב-
[אתר תיעוד Node.js](https://nodejs.org/en/download)

שמור את הקובץ ובדוק את הדפדפן. תמצא את תווית ההתקנה בתפריט הצד. כאשר אתה לוחץ על הקישור, התוכן של installation.mdx מעבד בדף:

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

שימוש ברכיבי React

קבצי MDX יכולים לכלול JSX, שזו השפה שבה משתמשת React. אתה יכול ליצור רכיב בתוך תיקיית הרכיבים ולייבא אותו בכל אחד מהמסמכים באתר שלך.

אתה יכול לראות דוגמה כיצד ניתן להטמיע רכיבים ב-Markdown ב- another.mdx קוֹבֶץ:

## רכיב
יבא את {useState} מ-'react'
ייבוא ​​סגנונות מ-'../components/counters.module.css'
ייצוא const Counter = () => { 
 const [count, setCount] = useState (0); 


 לַחֲזוֹר( 


 לחצו {count} פעמים


)
}

<דֶלְפֵּק />

## רכיבים חיצוניים
ייבוא ​​מונים מ'../components/counters'

<מונים />

קובץ Markdown זה מכיל הגדרה עבור רכיב ה-Counter. לאחר מכן, הוא מייבא את רכיב המונים מה- רכיבים מַדרִיך.

אם אתה מתכוון להשתמש באותו רכיב בכל אתר התיעוד שלך, עדיף ליצור אותו כרכיב עצמאי ולייבא אותו כשתזדקק לו.

למידע נוסף על Markdown

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