מהם מקטעים מתקפלים ב-Markdown?
Markdown פשוט למסמכים, ל-README ולתיעוד, אבל אין בו תחביר מובנה לאקורדיון. מפרסרים מודרניים תומכים ב-HTML5 בתוך השורה, בעיקר באלמנט <details> ובכיתוב <summary>, בלי תלות כבדה ב-JavaScript.
המחולל החינמי הופך מפרטים ארוכים, לוגים, שאלות נפוצות ודוגמאות קוד למיכלים נפתחים. הסריקה משתפרת בלי לוותר על תוכן רקע.
פירוק התחביר של details ו-summary
- תג העטיפה
<details>: המיכל שמחזיק את הכותרת הגלויה ואת הגוף המוסתר. המאפייןopen(<details open>) פותח את המיכל בטעינה. - תג הכותרת
<summary>: התווית שלוחצים עליה. אפשר לשלב עיצוב ו-Markdown בתוך האלמנט או לצדו.
דוגמת מבנה:
<details>
<summary>Click here to view detailed setup instructions</summary>
### Prerequisites
- Node.js v18+
- npm or yarn
Run the following command to install dependencies:
```bash
npm install utiliome-tools
</details>
```[!IMPORTANT] טיפ למפרסרי Markdown: רוב המעבדים (כולל GitHub Flavored Markdown) דורשים שורה ריקה אחרי
</summary>לפני גוף התוכן. בלי השורה, כותרות (###), רשימות (-) ובלוקי קוד מגודרים יוצגו כטקסט גולמי ולא כ-HTML.
שימושים נפוצים
1. ניקוי README ב-GitHub
מאגרים צריכים הוראות התקנה, משתני סביבה, יומן שינויים ופרמטרי API. עטיפת לוגים ארוכים ותצורות ב-<details> שומרת על README נקי.
2. דפי שאלות נפוצות
שאלות נפוצות מתאימות לאקורדיון: סורקים שאלות ופותחים רק את התשובה הרלוונטית.
3. הסתרת תוצאות בדיקה ו-stack traces
בתיאור pull request או בדיווח issue, לוג ענק מבלגן את הדיון. עטיפה במתג סגור שומרת את האבחון בלי להציף את השיחה.
4. תיעוד אינטראקטיבי
Docusaurus, MkDocs, Hugo, Jekyll ו-GitBook מרנדרים את האלמנטים. אפשר לקבץ מדריכים, מקרי קצה וקטעי קוד בפאנלים מתקפלים.
מדריך תאימות
| פלטפורמה / מפרסר | תמיכה ב-<details> |
Markdown בתוך Details | הערות |
|---|---|---|---|
| GitHub (GFM) | תמיכה מלאה | נתמך (דורש שורה ריקה אחרי <summary>) |
אידיאלי ל-README.md, לתיאורי PR ולתגובות issue. |
| GitLab | תמיכה מלאה | נתמך | פרסור HTML סטנדרטי. |
| Notion | בלוק Toggle מקומי | נתמך בייבוא | נדבק כבלוקי toggle. |
| Obsidian | תמיכה מקומית ו-HTML | נתמך | תוספים ותגי HTML. |
| Azure DevOps | תמיכה חלקית | בסיסית | תגי details פשוטים בוויקי. |
| Jekyll / Hugo | תמיכה מלאה | דורש הרחבת Markdown | פלט HTML תקין באתר סטטי. |
פרקטיקות מומלצות
- כותרות summary ברורות: הימנעו מ-"עוד מידע". העדיפו "הצגת תוצאות בנצ'מרק" או "הרחבת תבנית משתני סביבה".
- רמזים חזותיים: חצים, אייקוני תיקייה או אימוג'י (
▶️,🔍,📋) בתוך ה-summary מראים שהמקטע אינטראקטיבי. - הזחה נקייה: שמרו על הזחה ב-HTML או ב-Markdown מקונן כדי לא לשבור מהדרים קפדניים.
למלכודות תחביר ולמגבלות גודל ב-GitHub, ראו מקטעים מתקפלים ב-Markdown של GitHub.