מדריך סגנונות וארכיטקטורת Markdown

המסמך הזה הוא Source of Truth לעיצוב וארכיטקטורת Markdown בפרויקט. הוא מיועד למפתחים ול‑QA ויזואלי.

הערה

רינדור Reader Mode מתבצע בצד השרת ע״י Python‑Markdown, ובצד הלקוח נטענים סגנונות CSS (וגם Mermaid). בתצוגת md_preview יש גם רינדור צד‑לקוח, אבל ה‑Reader הוא בסיס הייחוס היציב לבדיקה ויזואלית.

1. סקירה טכנית (Architecture)

Pipeline קצר:

Markdown Text
Python‑Markdown (Extensions)
HTML
CSS Styling (Variables + Components)
User Display

Mermaid Diagram (תהליך הרינדור):

flowchart LR
  A[Markdown Text] --> B[Python Renderer (Extensions)]
  B --> C[HTML]
  C --> D[CSS Styling (Variables)]
  D --> E[User Display]

הערה

הדיאגרמה כתובה ב‑Mermaid אך מוצגת כטקסט כדי למנוע אזהרות Pygments ב‑RTD. אם רוצים רינדור ויזואלי, אפשר להוסיף תוסף Mermaid לתיעוד.

Extensions פעילים (מקור אמת: `app.py`):

Python‑Markdown Extensions
Extension	תפקיד
`extra`	חבילת הרחבות בסיסיות (למשל fenced code, attr_list, def_list). נותנת תשתית רחבה לפיצ׳רים נפוצים.
`codehilite`	הדגשת קוד בעזרת Pygments ועטיפה ב‑`.codehilite`.
`tables`	טבלאות בסגנון Markdown.
`sane_lists`	תיקון התנהגות רשימות (מונע שבירה בין פסקאות).
`toc`	יצירת תוכן עניינים (anchors לכותרות).
`admonition`	תיבות הודעה בסגנון `!!! note`.

Highlighting:

המנוע: Pygments
קלאס יעד: .codehilite
סגנון פעיל: friendly (הזרקה דרך Python)

2. מערכת הצבעים (Reader Mode)

משתני רקע חדשים (Reader Mode):

--reader-bg-light: #f5e6d3
--reader-bg-medium: #e8d4b0
--reader-bg-dark: #d4b896

רקע בסיסי (Sepia):

#fdf6e3 (משמש גם ל־reader-bg-sepia)

Highlighter (Pygments):

סגנון: friendly
מקור אמת: app.py (_PYGMENTS_PREVIEW_FORMATTER)

3. קטלוג רכיבים (Component Gallery)

Admonitions

דוגמה (Markdown):

!!! note
    זו הודעת Note.

!!! tip
    טיפ קצר.

!!! warning
    אזהרה חשובה.

!!! danger
    הודעת Danger.

CSS מקור: webapp/static/css/markdown-enhanced.css

Tables

דוגמה (Markdown):

| Feature | Status |
|---------|--------|
| Reader  | ✅     |
| Export  | ⏳     |

אזהרה

נכון לעכשיו אין Zebra Rows מובנה. אם צריך פסי זברה, יש להוסיף ב‑reader.css (למשל tbody tr:nth-child(even)).

CSS מקור: webapp/templates/md_preview.html (חלק ה‑Table Styles)

Task Lists

דוגמה (Markdown):

- [x] משימה שהושלמה
- [ ] משימה פתוחה

הערה

ב‑Reader Mode הרינדור נעשה בצד השרת, ולכן תיבות משימה דורשות הרחבה ייעודית אם רוצים להמיר ל‑checkbox אמיתי.

Mermaid

דוגמה (Markdown):

```mermaid
flowchart LR
  A --> B
```

אזהרה

Mermaid צריך theme ניטרלי על רקעים בהירים. ב‑Reader Mode האתחול הוא theme: 'neutral' + Overrides ב‑reader.css כדי לשמור על קווים וטקסט כהים.

Details / Summary

דוגמה (HTML בתוך Markdown):

<details class="markdown-details">
  <summary class="markdown-summary">לחץ לפתיחה</summary>
  <div class="details-content">תוכן מוסתר</div>
</details>

CSS מקור: webapp/static/css/markdown-enhanced.css

Code Blocks

דוגמה (Markdown):

```python
def hello():
    return "שלום"
```

CSS מקור: reader.css + ה‑CSS של Pygments (friendly).

4. הנחיות למפתחים (Best Practices)

לא להשתמש ב‑Inline Styles בתוך Markdown.
שינוי צבעים/רקעים נעשה ב‑reader.css או markdown-enhanced.css בלבד.
שמרו על התאמה בין Reader Mode ל‑Classic Theme כדי לשמר עקביות ויזואלית.

הערה

אם מוסיפים רכיב חדש, חובה לעדכן גם את מסמך ה‑Source of Truth הזה כדי ש‑QA ידע בדיוק מה אמור להופיע ובאילו קבצים.