Material for MkDocs: ערכת נושא, גרסאות, הגדרת Social Cards

תיעוד העולה על 200 עמודים דורש הגדרה מתקדמת: החיפוש מפסיק למצוא תוכן רלוונטי, ניהול גרסאות נפגע, ושיתוף קישורים לא מייצר תצוגות מקדימות. Material for MkDocs פותר את הבעיות הללו ישירות מהקופסה, אבל רק עם הגדרה נכונה. אנו מגדירים את הערכת הנושא, Social Cards, ניהול גרסאות באמצעות Mike, וחיפוש עם הדגשה — פתרון מלא.

אילו בעיות פותר הגדרת Material for MkDocs?

המערכת האקולוגית של Material for MkDocs היא לא רק ערכת נושא אלא פלטפורמה חזקה. חיפוש מובנה עם הדגשה, ניווט עם פירורי לחם, Google Analytics, משוב, תיוג — ערכת הנושא הסטנדרטית של MkDocs לא מספקת אפילו שליש מהפונקציונליות הזו.

נתקלנו בפרויקטים שבהם התיעוד גדל ליותר מ-200 עמודים, והחיפוש הפסיק למצוא את מה שצריך. הפתרון הוא להגדיר אינדוקס, להוסיף מילים נרדפות, ולהשתמש בתוסף search.suggest. בעיה נפוצה נוספת היא היעדר ניהול גרסאות: כשגרסת מוצר חדשה יוצאת, תיעוד ישן הופך לבלתי נגיש. Mike פותר זאת בהעלאה אחת. Material for MkDocs מייצר Social Cards פי 5 מהר יותר מ-ReadTheDocs ותומך ביותר מ-15 תוספים להרחבת הפונקציונליות.

למה כדאי שיהיה לך Material for MkDocs מוגדר באופן מקצועי?

הגדרה עצמית מובילה לעיתים קרובות לשגיאות: סדר תוספים שגוי שובר את הבנייה, Social Cards נכשלים ביצירה בגלל תלויות חסרות, וניהול גרסאות לא עובד בלי Mike. הגדרנו עשרות פרויקטים ואנחנו מכירים את כל המלכודות. זמן הגדרה ממוצע הוא 4–8 שעות. זמן שנחסך על ניפוי שגיאות הגדרה יכול לעלות על 20 שעות.

איך אנו מגדירים Material for MkDocs כפתרון מלא

אנו משתמשים בטכנולוגיות: MkDocs Material (הגרסה היציבה העדכנית ביותר), Python 3.11+, Mike לניהול גרסאות, תוספים git-revision-date-localized, minify, social. בקובץ ההגדרה אנו מאפשרים navigation.indexes, navigation.tabs, search.suggest, search.highlight. דוגמה מלאה ל-mkdocs.yml:

---
theme:
  name: material
  custom_dir: overrides
  logo: assets/logo.svg
  favicon: assets/favicon.png
  font:
    text: Inter
    code: JetBrains Mono
  features:
    - announce.dismiss
    - content.action.edit
    - content.action.view
    - navigation.footer
    - navigation.indexes
    - navigation.path
    - navigation.prune
    - navigation.sections
    - navigation.tabs
    - navigation.tabs.sticky
    - navigation.top
    - navigation.tracking
    - search.highlight
    - search.share
    - search.suggest
    - toc.follow
extra:
  version:
    provider: mike
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/my-org/my-project
  analytics:
    provider: google
    property: G-XXXXXXXXXX
  feedback:
    title: Эта страница полезна?
    ratings:
      - icon: material/thumb-up-outline
        name: Да, полезно
        data: 1
        note: Спасибо!
      - icon: material/thumb-down-outline
        name: Нет, нужно улучшить
        data: 0
        note: Напишите нам!
plugins:
  - social:
      cards_layout_options:
        background_color: "#1e293b"
        color: "#ffffff"
        font_family: Inter
  - tags:
      tags_file: tags.md
  - search:
      lang: ru
  - git-revision-date-localized
  - minify:
      minify_html: true
---

ליצירת Social Cards נדרשות הספריות theme: name: material custom_dir: overrides logo: assets/logo.svg favicon: assets/favicon.png font: text: Inter code: JetBrains Mono features: - announce.dismiss - content.action.edit - content.action.view - navigation.footer - navigation.indexes - navigation.path - navigation.prune - navigation.sections - navigation.tabs - navigation.tabs.sticky - navigation.top - navigation.tracking - search.highlight - search.share - search.suggest - toc.follow extra: version: provider: mike social: - icon: fontawesome/brands/github link: https://github.com/my-org/my-project analytics: provider: google property: G-XXXXXXXXXX feedback: title: Эта страница полезна? ratings: - icon: material/thumb-up-outline name: Да, полезно data: 1 note: Спасибо! - icon: material/thumb-down-outline name: Нет, нужно улучшить data: 0 note: Напишите нам! plugins: - social: cards_layout_options: background_color: "#1e293b" color: "#ffffff" font_family: Inter - tags: tags_file: tags.md - search: lang: ru - git-revision-date-localized - minify: minify_html: true ו-pillow. הכרטיסים נוצרים אוטומטית עבור כל עמוד.

הגדרת ניהול גרסאות באמצעות Mike

התקן את cairosvg והרץ:

pip install mike mike deploy --push --update-aliases 2.0 latest mike set-default --push latest 

כעת מופיע מתג גרסאות בתיעוד. זה מאפשר למשתמשים לעבור בין גרסאות יציבות ועדכניות.

יצירת Social Cards

הפעל את התוסף mike בקובץ pip install mike mike deploy --push --update-aliases 2.0 latest mike set-default --push latest כפי שמוצג למעלה. ודא ש-social ו-mkdocs.yml מותקנים. הכרטיסים נוצרים אוטומטית במהלך הבנייה.

התאמה אישית באמצעות Overrides

<!-- overrides/main.html -->
{% extends "base.html" %}
{% block announce %}
<div class="md-banner">
  🎉 Версия 2.0 вышла!
  <a href="/changelog">Что нового</a>
</div>
{% endblock %}
{% block styles %}
{{ super() }}
<link rel="stylesheet" href="{{ 'assets/custom.css' | url }}">
{% endblock %}

השוואה עם ערכות נושא אחרות

Material for MkDocs מייצר Social Cards פי 5 מהר יותר מאלטרנטיבות ותומך ביותר מ-15 תוספים. להתחלה מהירה, השתמש בקובץ ההגדרה המוכן — צור קשר ואנו נתאים אותו לפרויקט שלך.

בחירת תוספים: minify לעומת social

סדר התוספים חשוב: <!-- overrides/main.html --> {% extends "base.html" %} {% block announce %} <div class="md-banner"> 🎉 Версия 2.0 вышла! <a href="/changelog">Что нового</a> </div> {% endblock %} {% block styles %} {{ super() }} <link rel="stylesheet" href="{{ 'assets/custom.css' | url }}"> {% endblock %} צריך לבוא אחרי mkdocs-minify-plugin כדי לא לשבור את יצירת הכרטיסים.

תהליך

1. ניתוח מבנה התיעוד הנוכחי והצרכים שלך.
2. עיצוב הגדרות ותבניות מותאמות אישית.
3. הגדרת ערכת נושא, Social Cards, ניהול גרסאות, חיפוש ותוספים נוספים.
4. בדיקה בסביבת staging.
5. העלאה לסביבת production ומסירת גישה.

לוח זמנים: 4 עד 8 שעות בהתאם למורכבות. התמחור אישי.

רשימת בדיקה לשגיאות הגדרה נפוצות

• תלויות חסרות ל-Social Cards (pillow, cairosvg).
• social שגוי — overrides לא מיושמים.
• ניהול גרסאות נכשל כי minify חסר ב-extra.version.provider.
• החיפוש לא מאנדקס טקסטים ברוסית ללא הגדרת social.
• קונפליקט תוספים: minify שובר את Social Cards — סדר התוספים חשוב.

מה כלול

• הגדרת custom_dir מלאה לפרויקט שלך.
• הגדרת Social Cards עם המותג שלך.
• ניהול גרסאות באמצעות Mike.
• העברת תיעוד קיים (במידת הצורך).
• הדרכת צוות על MkDocs ו-Mike.
• אחריות ל-30 יום להתאמות.

הניסיון שלנו: 5+ שנים עם MkDocs, יותר מ-50 פרויקטי תיעוד. יש לנו הסמכות והמלצות. קבל ייעוץ על הגדרה — נעזור לך לבחור את ההגדרה הנכונה לפרויקט שלך. הזמן הגדרה עכשיו וקבל אחריות ל-30 יום.

מקור: תיעוד רשמי של Material for MkDocs