בפעם הראשונה README שלי חצה אלף שורות, עשיתי מה שכולם עושים: אני גללתי. ואז גללתי עוד קצת. איפשהו מסביב למעבר הרביעי מחפש את "Deployment" סעיף, ויתרתי והתחלתי לכתוב בכתב יד תוכן עניינים בראש הקובץ. זה עבד עד ששיניתי את שם הכותרת, שכחתי לעדכן את הקישור ושלחתי README שבו "Configuration" הצביע על כלום. קישור שבור בעמוד בתיעוד שלך הוא דבר קטן, אבל זה מסוג הדברים הקטנים שאומרים לקורא שאף אחד לא אכפת לו מהחנות.
אני בונה [Toolz.dev] (/, אוסף של כלי עזר למפתחים מבוססי דפדפן, ואני מתחזק הרבה Markdown: מדריכי כלים, קבצי README, מפרט פנימי והמסמכים שאתה קורא עכשיו תוכן עניינים שאני צריך לשמור ביד הוא תוכן עניינים שבסופו של דבר ישקר אז בניתי את מחולל TOC Markdown לעשות את החלק המשעמם בצורה נכונה בכל פעם, והמדריך הזה הוא כל מה שלמדתי על קישורי עוגן תוך כדי בנייתו.
TL;DR: תוכן עניינים של Markdown הוא רשימה מקוננת של קישורים שקופצים לכותרות באותו עמוד הקישורים פועלים מכיוון שכל כותרת מקבלת מזהה עוגן אוטומטי, וה-slug ש-GitHub מקצה עוקב אחר כלל ספציפי: אותיות קטנות של הטקסט, זרוק סימני פיסוק מלבד מקפים, והפוך רווחים למקפים. הדבק את ה-Markdown שלך במחולל, בחר אילו רמות כותרת לכלול והעתק את הרשימה הכלי מחשב את העיבודים המדויקים של slugs GitHub, כולל
-1סיומת לכותרות כפולות, כך ששום דבר לא נשבר כשאתה מדביק אותו בחזרה.
מהו תוכן עניינים של Markdown?
תוכן עניינים ב-Markdown אינו תחביר מיוחד. CommonMark לא מגדיר מבנה כזה, וגם GitHub Flavored Markdown. זוהי רשימה רגילה שבה כל פריט הוא קישור, וכל קישור מצביע על עוגן בתוך אותו מסמך. כאשר מעבד Markdown כמו GitHub הופך כותרת ל-HTML, הוא גם נותן לכותרת זו id תכונה. כותרת שנכתבה כ ## Getting Started הופך להיות בערך <h2 id="getting-started">Getting Started</h2>. ברגע שהזיהוי הזה קיים, קישור כתוב כ [Getting Started](#getting-started) גולל אליו את הדף.
אז תוכן עניינים הוא רק אוסף של הקישורים האלה, מחורצים כדי לשקף את היררכיית הכותרות:
- [Getting Started](#getting-started)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
הטריק כולו חי במילה אחת מאותה דוגמה: העוגן. Get the anchor wrong and the link silently fails, scrolling nowhere.Get it right and the content block works on GitHub, in most static-site generators, and inside documentation platforms that follow the same convention החלק הקשה הוא לא לכתוב את הרשימה החלק הקשה הוא לחזות את ה-id המדויק שכל מעבד יקצה, וזו הסיבה לעשות את זה ביד זה משחק מפסיד בכל מסמך שמשתנה.
כיצד נוצרים בפועל עוגני כיוון?
GitHub's אלגוריתם slug הוא דטרמיניסטי ושווה לשנן, כי ברגע שאתה יודע את זה אתה יכול לחזות כל עוגן בדף השלבים, לפי הסדר, הם: המרת טקסט הכותרת לאותיות קטנות, הסר כל תו שאינו אות, מספר, רווח או מקף, ולאחר מכן החלף כל רווח במקף זה הכלל כולו.
ההשלכות הן המקום שבו אנשים מטיילים שקול כותרת כמו ## Set Up & Config. כיסוי תחתון נותן set up & config. הסרת האמפרסנד (אך השארת הרווחים סביבו) נותנת set up config עם שני חללים שבהם ה & היה פעם. turning spaces into hyphens produces set-up--config, עם מקף כפול המקף הכפול הזה נראה כמו טעות, אבל זה בדיוק מה ש-GitHub מעבד, אז זה בדיוק מה שהקישור שלך צריך. כלי ש-" מנקה up" המקף הכפול ייצור קישור שלא נפתר.
כותרות כבדות פיסוק קורסות רחוק יותר ממה שאתה מצפה. ## C++ Guide הופך c-guide, כי שני סימני הפלוס מופשטים והשארית הופכת למקף בודד. ## What's New? הופך whats-new, כי האפוסטרופ וסימן השאלה נעלמים. Emoji ורוב הסמלים נעלמים לחלוטין. ה מחולל TOC Markdown מחיל את תו הכלל הזה עבור תו כך שה-slug שהוא מראה לך הוא המזהה ש-GitHub יבנה, ללא ניחוש מעורב.
מה קורה כששתי כותרות זהות?
מסמכים חוזרים על כותרות. יומן שינויים עשוי לכלול שלושה חלקים שכולם נקראים ### Fixed. אם כל אחד מהם ייצר את slug fixed, רק הקישור הראשון יעבוד. GitHub פותר זאת על ידי מספור הכפילויות: הראשון Fixed מקבל fixed, השני מקבל fixed-1, השלישי מקבל fixed-2, וכן הלאה בסדר מסמכים הסיומת מצורפת אחרי הבסיס slug עם מקף.
זו אחת הסיבות הנפוצות ביותר תוכן עניינים בכתב יד נסחף מסונכרן אתה מוסיף סעיף שני עם שם שכבר השתמשת, העוגן הופך בשקט -1, והקישור הישן שלך מצביע כעת על המקום הלא נכון או בשום מקום בכלל. המחולל עוקב אחר כל slug שהוא פלט ומחיל את אותה סיומת מספרית, כך שכותרות חוזרות ונשנות מקשרות להתרחשות הנכונה.
אילו סוגי כותרות קורא הכלי?
ל-Markdown יש שני סגנונות כיוון, ומחולל שלם צריך לקרוא את שניהם. הנפוץ הוא ATX, כאשר שורה מתחילה באחד עד שש # תווים ואחריהם טקסט הכותרת ספירת הגיבובים היא הרמה, אז # הוא H1 ו ###### הוא H6. הסגנון השני הוא Setext, כאשר שורת טקסט מסומנת בקו תחתון בשורה הבאה עם סימני שוויון עבור H1 או מקפים עבור H2:
Document Title
==============
A Section
---------
שני הסגנונות מייצרים כותרות עם מזהי עוגן, כך ששניהם שייכים לתוכן עניינים. החלק המסובך עם Setext הוא להבדיל בין כותרת מודגשת אמיתית לכלל אופקי, מכיוון ששורה של מקפים יכולה להיות אחת מהן. הכלל שבו משתמש המחולל הוא שקו תחתון של מקף נחשב ככותרת רק כאשר השורה ישירות מעליו היא טקסט פסקה רגיל, לא שורה ריקה, פריט רשימה, ציטוט בלוק או מבנה בלוק אחר. א --- לשבת לבד עם שורות ריקות סביבו זו הפסקה נושאית, ומתעלמים ממנה נכון.
יש עוד קטגוריה אחת לטפל בה, והיא זו שהורסת בשקט כלים נאיביים: כותרות בתוך קוד אם המסמך שלך מכיל בלוק קוד מגודר המציג פקודות מעטפת, חלק מהשורות האלה יתחילו עם # כהערות אלה אינן כותרות, ואסור להן להופיע בתוכן לעולם המחולל עוקב אחר גושי קוד מגודרים (אלה שתוחמים על ידי טריפל בקטיקים או טריפל טילדות) ומדלג על כל # שורה בתוכם הערת מעטפת כמו # install dependencies בדוגמה נשאר איפה שהוא שייך, בדוגמה.
איך אני שולט בעומק תוכן העניינים?
תוכן עניינים המפרט כל כותרת עד H6 אינו תוכן עניינים, הוא עותק שני של המסמך. רוב READMEs קוראים בצורה הטובה ביותר כאשר התוכן מכסה את H2 ו-H3 בלבד, ומעניקים לקוראים את המדורים העיקריים ואת ילדיהם המיידיים מבלי להטביע אותם בפירוט. המחולל מאפשר לך להגדיר רמה מינימלית ומקסימלית, והוא כולל רק את הכותרות הנופלות בטווח זה.
ההתנהגות העדינה כאן היא הזחה אם אתה כולל H2 עד H4, הכותרת הרדודה ביותר ששמרת היא H2, והיא צריכה לשבת צמוד לשוליים השמאליים ולא מחורצת כאילו H1 בלתי נראה מעליו. המחולל מודד את עומק הקינון ביחס לכיוון הרדוד ביותר שהוא כולל בפועל, כך שבלוק תוכן שמתחיל ב-H2 מתחיל ללא שקע. זה ההבדל בין רשימה שנראית מכוונת לבין כזו שנראית כאילו איבדה את העמודה הראשונה שלה.
אתה גם מקבל לבחור את סמן הרשימה רשימה לא מסודרת משתמשת כדור עבור כל ערך, אשר הוא המראה המקובל עבור README רשימה מסודרת מספרים את הערכים, ואת המחולל מחדש את הספירה בתוך כל רמת קינון כך מתאר ממוספר קורא נכון ולא לספור ישר דרך מאחד עד חמישים הזחה יכולה להיות שני רווחים, ארבעה רווחים, או כרטיסייה, תלוי מה שאר המסמך שלך משתמש.
מה לגבי כותרות מודגשות ולא לטיניות?
לא כל כותרת היא אנגלית פשוטה, וכלל slug צריך להתמודד. GitHub שומר אותיות מאלפביתים אחרים במקום להפשיט אותם, אז כותרת כמו ## Configuración שומר על הדמויות המודגשות שלו והופך configuración, וכותרת בקירילית או יוונית שומרת גם את האותיות הללו. מה שמוסר הוא סימני פיסוק וסמלים, לא אותיות, ללא קשר לסקריפט. המחולל פועל לפי אותו עיקרון על ידי התייחסות לכל אות או ספרה של Unicode כאל תו slug חוקי, כך שמסמך רב לשוני מייצר עוגנים התואמים למה ש-GitHub מעבד ולא שורה של קישורים ריקים.
זה חשוב יותר ממה שזה נראה לראשונה צוותים שכותבים תיעוד בספרדית, גרמנית או יפנית מוצאים לעתים קרובות שכלים תמימים slug מעוותים את הכותרות שלהם לעוגנים בלתי שמישים, מכיוון שהכלים האלה מניחים ASCII. אם הקישורים שלך אי פעם לא הצביעו על כלום ב-README מתורגם, slug שהשליך בשקט את האותיות שאינן ASCII הוא כמעט בוודאות הסיבה לכך. יצירת בלוק התוכן עם כלי מודע ל-Unicode מסירה את כל המחלקה של קישורים שבורים, ומשמעות הדבר היא שאותו מסמך יכול להחזיק כותרות ביותר משפה אחת מבלי שאף אחד מהם יאבד את העוגנים שלו.
מתי עלי להשתמש ב-TOC שנוצר לעומת אוטומטי?
חלק מהפלטפורמות בונות עבורכם תוכן עניינים. GitLab תומך ב [[_TOC_]] token, חלק מהוויקי מחדירים תיבת תוכן באופן אוטומטי, ומסגרות תיעוד כמו Docusaurus מציגות מתאר בעמוד מהכותרות שלך מבלי שתכתוב דבר. כאשר אתה עובד בתוך אחת מהמערכות הללו, השתמש בתכונה המובנית. זה נשאר עדכני באפס מאמץ מכיוון שהפלטפורמה מחדשת אותו בכל עיבוד.
הגנרטור מרוויח את מקומו בכל מקום אחר, ו-"בכל מקום אחר" הוא מקום גדול. GitHub READMEs אינם יוצרים אוטומטית בלוק תוכן, ולכן דף נחיתה של מאגר זקוק לרשימת Markdown אמיתית המחויבת לקובץ. Markdown שמומר למשהו אחר, נשלח בדואל, מודבק לבעיה או מעובד על ידי צופה מינימלי זקוק לבלוק תוכן סטטי מכיוון שאין מנוע לבנות אחד תוך כדי תנועה. הטבלה שלהלן מפרטת היכן כל גישה מתאימה.
| מצב | הגישה הטובה ביותר | למה |
|---|---|---|
| GitHub README | רשימה סטטית שנוצרה | GitHub מעבד מזהי כותרת אך אינו מכניס TOC אוטומטית |
| ויקי GitLab או מסמכים | [[_TOC_]] טוקן |
יליד, תמיד עדכני |
| עמוד דוקוסאורוס / MkDocs | מתאר מובנה | Framework מעבד אותו מכותרות |
| קובץ סימון רגיל לייצוא | רשימה סטטית שנוצרה | אין מעבד לבנות אחד בזמן צפייה |
| הנפק או משוך תיאור בקשה | רשימה סטטית שנוצרה | עוגנים עובדים, אבל שום דבר לא יוצר את הרשימה אוטומטית |
כלל האצבע: אם הדבר שמציג את ה-Markdown שלך יכול לבנות את התוכן עצמו, תן לו. אם ה-Markdown שלך עשוי להיקרא במקום שאינו יכול, צור את הרשימה ובצע אותה. כאשר אתה ממיר בין פורמטים, ה Markdown כדי HTML ממיר וה HTML לממיר Markdown זוג באופן טבעי עם בלוק תוכן שנוצר, מכיוון שהעוגנים שורדים את הנסיעה הלוך ושוב.
איך זה מתאים לשאר זרימת העבודה של Markdown?
תוכן עניינים הוא חלק אחד של שמירה על מסמכים ארוכים קריאים, והוא עובד הכי טוב לצד כמה הרגלים. שמור על טקסט הכותרת שלך יציב לאחר שפרסמת אליו קישורים, מכיוון ששינוי שם של כותרת משנה את slug שלו ושובר כל קישור שהצביע עליו. כאשר אתה משנה את השם, שחזר את התוכן במקום לערוך את הקישור האחד שאתה זוכר, מכיוון ששינוי שם מעביר לעתים קרובות את מספור הסיומת הכפולה בהמשך הקובץ.
תוכן מובנה נהנה מכלים אחרים באותה משפחה כאשר מסמך נשען על נתונים טבלאיים, ה מחולל טבלאות סימון בונה טבלאות צינור מיושרות כהלכה שטבלה שהוקלדה ביד כמעט אף פעם לא מקבלת נכון כאשר אתה יורש HTML מבולגן שצריך להפוך ל-Markdown נקי, או Markdown נקי שצריך להפוך ל-HTML, הממירים מטפלים בתרגום תוך שמירה על מבנה הכותרת ואם אתה ביקורת מסמך עבור אורך או איזון מילות מפתח, ה מונה מילים נותן לך את המספרים מבלי להדביק את הטיוטה שלך לשום דבר מבוסס ענן.
הכל פועל בדפדפן, מה שחשוב יותר ממה שזה נשמע. README מכיל לעתים קרובות שמות תכונות שלא פורסמו, כתובות URL פנימיות או פרטי לקוח, ואין להעלות שום דבר מזה לשרת של צד שלישי רק כדי לבנות רשימה של קישורים המחולל מנתח את ה-Markdown שלך עם JavaScript בצד הלקוח, כך שהמסמך לעולם לא עוזב את המחשב שלך אם פרטיות בכלי מפתחים היא משהו שאתה חושב עליו, הכתיבה על פרטיות נתונים וכלים מקוונים מכסה מדוע עיבוד מקומי הוא ברירת המחדל הנכונה, ואת ערכת כלים למפתחי אינטרנט מסכם את שאר השירותים אליהם אני מגיע מדי יום.
דוגמה שעבדה במהירות
נניח שיש לך מסמך זה:
# Payment Service
## Getting Started
### Requirements
### Local Setup
## API Reference
### Authentication
### Errors
## Deployment
הגדר את הטווח ל-H2 עד H3, בחר רשימה עם תבליטים והשאיר קישורי עוגן דולקים. המחולל מייצר:
- [Getting Started](#getting-started)
- [Requirements](#requirements)
- [Local Setup](#local-setup)
- [API Reference](#api-reference)
- [Authentication](#authentication)
- [Errors](#errors)
- [Deployment](#deployment)
הכותרת H1 אינה נכללת מכיוון שהיא יושבת מעל הטווח, קטעי H2 סמוכים שמאלה, וילדיהם H3 מחורצים ברמה אחת. הדבק את החסימה הזו ממש מתחת לכותרת ב-README שלך וכל ערך קופץ לקטע שלו ב-GitHub. זו כל העבודה, שנעשתה בזמן שלוקח לקרוא את המשפט הזה, והיא נשארת נכונה כי מכונה חישבה את slugs במקום אותך.
שאלות נפוצות
כיצד פועל תוכן עניינים של Markdown?
תוכן עניינים של Markdown הוא רשימה של קישורים המצביעים על עוגני כותרת בתוך אותו עמוד. לכל כותרת במסמך Markdown ניתן מזהה אוטומטי, וקישור כתוב כ סעיף קופץ אליו כלי זה קורא את הכותרות שלך, בונה את העוגנים התואמים, ומרכיב עבורך את הרשימה המקוננת.
כיצד נוצרים קישורי העוגן?
עוגנים עוקבים אחר כלל GitHub slug: טקסט הכותרת הוא באותיות קטנות, סימני פיסוק שאינם מקפים מוסרים, והרווחים הופכים למקפים. " הגדר & Config" הופך להגדרת המזהה--config. כאשר שתי כותרות מייצרות את אותו slug, השנייה מקבלת סיומת -1, השלישית -2 וכן הלאה, התואמת את האופן שבו GitHub מעבד אותן.
האם זה עובד עם קבצי GitHub README?
כן. האלגוריתם slug משקף את זה ש-GitHub משתמש בו כדי לעבד מזהי כותרות, כך שקישורי תוכן העניינים נפתרים כהלכה בתוך README ב-github.com. הדבק את ה-README שלך, בחר את רמות הכותרת שלך ושחרר את הרשימה שנוצרה מתחת לכותרת.
האם אוכל לבחור אילו רמות כותרת מופיעות?
כן. הגדר רמה מינימלית ומקסימלית, למשל H2 עד H4, ורק כותרות בטווח זה כלולות. עומק הקינון נמדד ביחס לכותרת הכלולה הרדודה ביותר, כך שהמתאר לעולם לא מתחיל בשקע ריק גדול.
האם כותרות בתוך בלוקי קוד כלולות?
מס 'קווים שמתחילים ב # בתוך בלוק קוד מגודר (מוגדר על ידי טריפל backticks או טריפל טילדות) מטופלים כקוד, לא כותרות, כך קטעי דוגמה והערות מעטפת לעולם לא מופיעים בתוכן העניינים.
מה ההבדל בין TOC מסודר ללא מסודר?
תוכן עניינים לא מסודר משתמש בסמני כדורים כגון מקף עבור כל ערך, בעוד שמסודר משתמש במספרים שמתגברים בתוך כל רמת קינון. בחר מסודר כאשר הקוראים נהנים מקו מתאר ממוספר, ולא מסודר עבור בלוק תוכן קל יותר ורגיל יותר.
האם הכלי תומך בכותרות Setext?
כן. הוא קורא גם כותרות ATX שמתחילות בכותרות # וגם כותרות Setext, כאשר שורת טקסט מסומנת בקו תחתון עם סימני שוויון עבור H1 או מקפים עבור H2. שני הסגנונות מומרים לעגן קישורים באותו אופן.
האם מחולל Markdown TOC הוא חינמי ופרטי?
כן. זה לגמרי בחינם ללא הרשמה וללא מגבלות. כל הניתוח מתרחש בדפדפן שלך באמצעות JavaScript בצד הלקוח, כך שה-Markdown שאתה מדביק לעולם לא עוזב את המכשיר שלך והכלי ממשיך לעבוד במצב לא מקוון לאחר טעינת הדף.
