מדריך סגנונות וארכיטקטורת 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`):
Extension |
תפקיד |
|---|---|
|
חבילת הרחבות בסיסיות (למשל fenced code, attr_list, def_list). נותנת תשתית רחבה לפיצ׳רים נפוצים. |
|
הדגשת קוד בעזרת Pygments ועטיפה ב‑ |
|
טבלאות בסגנון Markdown. |
|
תיקון התנהגות רשימות (מונע שבירה בין פסקאות). |
|
יצירת תוכן עניינים (anchors לכותרות). |
|
תיבות הודעה בסגנון |
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/static/css/md-content-layout.css; הצבעים — קווי התאים ורקע הכותרת — ב‑webapp/static/css/md-content-colors.css. שני הקבצים משותפים לתצוגת המסמך ולתצוגה החיה. הכיוון והיישור של כל תא נקבעים לפי התוכן שלו: כיוון של קוד בשורה ותאי טבלה.
Task Lists
דוגמה (Markdown):
- [x] משימה שהושלמה
- [ ] משימה פתוחה
הערה
ב‑Reader Mode הרינדור נעשה בצד השרת, ולכן תיבות משימה דורשות הרחבה ייעודית אם רוצים להמיר ל‑checkbox אמיתי.
Mermaid
דוגמה (Markdown):
```mermaid
flowchart LR
A --> B
```
אזהרה
Mermaid צריך theme ניטרלי על רקעים בהירים. ב‑Reader Mode
האתחול הוא theme: 'neutral' + Overrides ב‑reader.css
כדי לשמור על קווים וטקסט כהים.
הערה
רוחב התוויות. בתצוגת המסמך, בתצוגה החיה ובייצוא המעוצב (גם בקישור השיתוף שלו), תווית בתרשים נשברת לשורות רק כשהיא רחבה מ-MERMAID_WRAPPING_WIDTH (ב-webapp/static_build/mermaid-site-config.mjs), שרחב מברירת המחדל של Mermaid. תווית צרה ממנו נשארת בשורה אחת. Mermaid מחליט לפי המדידה של התווית, בסובלנות של פיקסל (webapp/static_build/mermaid-label-wrap-fix.mjs), ולכן תווית שצרה מהרוחב בפחות מפיקסל מקבלת תיבה ברוחב הזה בדיוק — ועדיין בשורה אחת. תרשים בודד יכול לקבוע רוחב אחר בהנחיה בראש התרשים, והיא גוברת על הרוחב של האתר לתרשים ההוא בלבד:
```mermaid
%%{init: {"flowchart": {"wrappingWidth": 250}}}%%
flowchart LR
A --> B
```
מצב הקריאה טוען Mermaid משלו, ושם נשארת ברירת המחדל של Mermaid.
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).
בתצוגת המסמך ובתצוגה החיה הבלוק — מסגרת, פס כותרת עם שם השפה וכפתור העתקה — נבנה ב‑webapp/static/js/md-code-blocks.js. הפריסה שלו ב‑md-content-layout.css, והצבעים, כולל צבעי התחביר, ב‑md-content-colors.css.
Highlight (==מארקר==)
דוגמה (Markdown):
טקסט עם ==הדגשת מארקר== באמצע המשפט.
הרכיב הזה קיים רק בצד הלקוח, ולכן הוא היוצא מן הכלל היחיד בעמוד הזה שאין לו
מקבילה ב‑Reader Mode. ל‑Python‑Markdown לא נטען pymdownx.mark, ולכן שם
==טקסט== מוצג כטקסט גולמי. מי שבודק ויזואלית צריך לדעת את זה מראש: פער בין
התצוגות כאן אינו באג ברינדור.
מקור: webapp/static/js/md-mark-plugin.js — תוסף markdown-it יחיד, משותף
לתצוגת המסמך (md_preview.html) ול‑Live Preview (live-preview.js). כל תבנית
שטוענת אחד משניהם חייבת לטעון גם אותו, לפניו.
אזהרה
התוסף בנוי על מנגנון הדלימיטרים התקני של markdown-it — scanDelims,
state.delimiters ו‑postProcess שרשום על ruler2 — במבנה של
rules_inline/strikethrough.mjs שבספרייה. אין לקרוא לinline.parse
מתוך כלל inline: היא מריצה את שלבי הסיום על מערך הטוקנים המשותף ומקצרת אותו,
והאינדקסים של דלימיטרים חיצוניים (**) מצביעים אז מעבר לסופו. הגרסה הקודמת
עשתה בדיוק את זה, והפילה את כל התצוגה על כל מסמך שהכיל הדגשה ואחריה מארקר באותה
פסקה. tests/md-mark-plugin.test.js שומר על ההתנהגות.
נוסחאות ($...$, $$...$$)
דוגמה (Markdown):
הנוסחה המפורסמת של איינשטיין: $E = mc^2$
$$
\begin{bmatrix}
a & b \\
c & d
\end{bmatrix}
$$
הנוסחאות מזוהות בתוך הפענוח של markdown-it, ולא על ה-HTML המוכן. לכן התוכן עובר ל-KaTeX בדיוק כמו שנכתב: \\ של מטריצה נשאר \\, ו-_ או * בתוך נוסחה אינם הופכים להדגשה. כמו המארקר, גם הרכיב הזה קיים רק בצד הלקוח: ב-Reader Mode, _render_markdown_preview (webapp/app.py) לא טוען הרחבה של נוסחאות, ושם $...$ מוצג כטקסט.
מתי ``$`` הוא נוסחה. הבסיס הוא הכללים של pandoc (הסעיף tex_math_dollars ב-MANUAL.txt שלו), ועליהם כללים משלנו, כי pandoc פוסל רק ספרה אחרי ה-$ הסוגר, וזה לא מספיק לטקסט שלנו. הנימוק המלא, עם המקרים שהכללים נבנו מהם, נמצא בהערה שבראש md-math-plugin.js:
אחרי ה-
$הפותח אין רווח, ולפני ה-$הסוגר אין רווח. הסוגר הוא ה-$הראשון אחרי הפותח, ואם הוא לא עומד בכללים — אין נוסחה.$שצמוד מבחוץ לאות לטינית או לספרה אינו גבול של נוסחה (isWordChar). כךעולה $5 ובפרימיום $10,$substrCPו-$substrBytesבאותה פסקה, ו-$$ROOTשל מונגו נשארים טקסט. המחיר:$n$thאינו נוסחה. אותיות עבריות לא נכללות בכלל הזה, ולכןב-$x$הוא כן נוסחה.$שמיד אחריו בא$נוסף אינו סוגר: הוא תחילת$$.אות עברית מחוץ לסוגריים מסולסלים מבטלת נוסחה בתוך שורה (
hasBareHebrew). ב-TeX אות עברית אינה סמל של נוסחה, ועברית בתוך נוסחה נכתבת בקבוצה, כמו\text{מרחק}— וזה ממשיך לעבוד. כך$10, ולפעמים 5$, מחיר בשני הסגנונות באותה פסקה, נשאר טקסט. בלוק$$אינו בכלל הזה.גרש הפוך לפני ה-
$הסוגר מבטל את הנוסחה (findCloser): קוד אף פעם לא נבלע בתוך נוסחה, ו-$שבתוך קוד נשאר טקסט.\$מציג סימן דולר רגיל.בלוק
$$(mathBlock) נפתח בשורה שמתחילה ב-$$, ונסגר בשורה שבה נמצא ה-$$הבא, בלי שורה ריקה ביניהן. השורות שבתוכו לא מפוענחות כבלוקים:=לבד בשורה כבר לא הופך את המטריצה לכותרת. בלוק שלא נסגר נשאר טקסט, ולא בולע את המשך המסמך.
מקור: webapp/static/js/md-math-plugin.js — תוסף markdown-it יחיד, משותף לתצוגת המסמך (md_preview.html) ול‑Live Preview (live-preview.js). כל תבנית שטוענת אחד מהם חייבת לטעון גם אותו, לפניו. KaTeX מגיע מהבאנדל: window.katex מוגדר ב-webapp/static_build/md-preview-entry.js, ואחרי כל שינוי שם צריך לבנות מחדש את md_preview.bundle.js (npm run build-md). tests/md-math-plugin.test.js שומר על ההתנהגות, ובודק גם שהבאנדל שבריפו חושף את window.katex.
מה רואים: כל נוסחה עטופה ב-dir="ltr", כי ל-CSS של KaTeX אין הגדרת כיוון, ובלי זה עמוד עברי הציג את E = mc^2 כ-²mc = E. שגיאה בתחביר של TeX מוצגת באדום, וההודעה שלה מופיעה ב-title. תקלה אחרת בנוסחה אחת, למשל קינון עמוק מאוד של סוגריים, מציגה את המקור של הנוסחה (md-math-error) ולא מפילה את המסמך.
אזהרה
כלל ה-inline לא קורא לinline.parse. התוכן של נוסחה אינו Markdown, ולכן הכלל לוקח את המקור הגולמי ולא מפענח אותו. קריאה ל-inline.parse מתוך כלל inline היא מה שהפיל את כל התצוגה בתוסף המארקר (הסעיף הקודם).
הערה
איפה נוסחה כבר לא מרונדרת. קודם renderMathInElement רץ על כל ה-HTML, ולכן רינדר נוסחאות גם במקומות שה-Markdown שלהם לא מפוענח: בכותרת של בלוק ::: ובתוכן העניינים ([[toc]]). היום הן נשארות שם טקסט. בתוכן העניינים ובעוגן של כותרת, החלק של הנוסחה פשוט לא נכלל, כי markdown-it-anchor (9.2.0) ו-markdown-it-toc-done-right (4.2.0) לוקחים מהכותרת רק טוקנים של טקסט ושל קוד. מכיוון ששניהם עושים זאת באותה צורה, הקישור מתוכן העניינים עדיין מגיע לכותרת.
קישורים אוטומטיים
דוגמה (Markdown):
המדריך ב-https://example.com/guide, ושאלות אל someone@example.com.
הקבצים: readme.md, app.py, notes.org
כתובת שנכתבה עם פרוטוקול הופכת לקישור גם בלי [טקסט](כתובת), ושם של קובץ נשאר טקסט. בדוגמה הכתובת והמייל הם קישורים, ו-readme.md, app.py ו-notes.org לא.
מה הופך לקישור: כתובת שמתחילה בפרוטוקול שיש לו כלל ב-defaultSchemas של linkify-it (http://, https://, ftp://, mailto: ו-//), וכתובת מייל. www.example.com ו-example.com בלי פרוטוקול נשארים טקסט. זו החלטה של בעל הפרויקט (נובמבר 2026): כלל אחד וברור, בלי כלל נוסף ל-www. כמו בגיטהאב. מי שרוצה קישור כותב את הכתובת עם https://, או [טקסט](כתובת).
למה. markdown-it נוצר עם linkify: true, ו-linkify-it מנחש כברירת מחדל כתובות גם בלי פרוטוקול (fuzzyLink): כל מילה.XX שבה XX הוא קוד מדינה בשתי אותיות, ועוד סיומות כמו com ו-org. עד נובמבר 2026 זה הפך שמות של קבצים לקישורים: readme.md (md הוא קוד המדינה של מולדובה) הוצג כקישור ל-http://readme.md, והלחיצה הובילה לדף שגיאה של הדפדפן. רשימה של סיומות לא הייתה פותרת את זה, כי .org, .com ו-.pro הן גם סיומות של קבצים וגם של אתרים.
מקור: webapp/static/js/md-linkify-plugin.js — תוסף markdown-it שמכבה את fuzzyLink. כל מקום שיוצר את markdown-it עם linkify: true מתקין אותו: תצוגת המסמך (md_preview.html), הרנדרר של live-preview.js (ensureRenderer), שמשמש את ה‑Live Preview, את הייצוא המעוצב, את דפדפן הריפו ואת כרטיסי החיפוש בתיעוד, ומסלול הגיבוי של דפדפן הריפו (renderMarkdownFallback ב-repo-browser.js). ההסבר המלא, עם המקורות בספרייה, בראש התוסף. tests/md-linkify-plugin.test.js שומר על ההתנהגות, ובודק שכל מקום כזה מתקין את התוסף ושכל תבנית שמארחת רנדרר טוענת אותו. tests/test_md_autolink_browser.py בודק את אותו דבר בכרומיום, בעמודים האמיתיים.
כמו המארקר והנוסחאות, גם זה קיים רק בצד הלקוח. ב-Reader Mode, ההרחבות ש-_render_markdown_preview (webapp/app.py) טוען לא הופכות כתובת חשופה לקישור (נבדק ב-Python-Markdown 3.9), ושם גם https://example.com נשאר טקסט.
קישור נפתח בלשונית חדשה
דוגמה (Markdown):
[המדריך](https://example.com/guide), [קובץ באתר](/file/abc), [לסעיף הבא](#סיכום) ו-[מייל](mailto:someone@example.com).
לחיצה על קישור שמוביל לעמוד פותחת אותו בלשונית חדשה, והעמוד שקוראים בו נשאר במקומו. בדוגמה המדריך ו-קובץ באתר נפתחים בלשונית חדשה. לסעיף הבא ו-מייל נשארים באותה לשונית.
מה נפתח בלשונית חדשה: כתובת ב-http:// או ב-https://, וכתובת בלי סכמה בכלל, כלומר נתיב באתר (/file/...), נתיב יחסי (docs/a.md) או //example.com. הקישור יוצא עם target="_blank" ו-rel="noopener noreferrer", כמו הקישורים בפתקים הדביקים.
מה נשאר באותה לשונית: עוגן בתוך המסמך (#...): תוכן העניינים, ¶ ליד כותרת, הערות שוליים וקישור פנימי שהכותב כתב. בלשונית חדשה כל אחד מהם היה פותח עותק של אותו עמוד. גם href ריק נשאר, וכך גם כל סכמה אחרת, כמו mailto:, tel: וקישור לאפליקציה: הם פותחים אפליקציה ולא עמוד בדפדפן. זו החלטה של בעל הפרויקט (נובמבר 2026).
למה. עד נובמבר 2026 לחיצה על קישור החליפה את העמוד. בתצוגת המסמך זה איבד את המקום בקריאה, ובתצוגה החיה בעמוד העריכה זה גם עזב את העורך באמצע העבודה.
מקור: webapp/static/js/md-link-target-plugin.js, תוסף markdown-it שמחליף את הכלל שכותב את תגית הפתיחה של קישור (link_open). לכן ה-HTML עצמו יוצא עם המאפיינים, בכל מקום שהוא מוצג: עמוד, קובץ HTML מעוצב שיורד וקישור שיתוף. כל מקום שיוצר את markdown-it מתקין אותו: תצוגת המסמך (md_preview.html), הרנדרר של live-preview.js (ensureRenderer, בכל הסוגים שלו), ומסלול הגיבוי של דפדפן הריפו (renderMarkdownFallback ב-repo-browser.js). הכלל וההסבר המלא נמצאים בראש התוסף.
גם בצד השרת. services/md_link_target.py מחיל את אותו כלל (opens_in_new_tab) כהרחבה של Python-Markdown, בשני הרנדררים של השרת. הראשון הוא _render_markdown_preview, שמשמש את Reader Mode ואת התצוגה החיה כשהרינדור בדפדפן נכשל. השני הוא markdown_to_html, שמשמש את הייצוא המעוצב כש-STYLED_EXPORT_BROWSER_RENDER כבוי. ההרחבה רצה אחרי unescape ומפענחת את ה-href של קישור מייל אוטומטי, שנשמר בעץ מקודד תו-תו. ההסבר נמצא בראש המודול. <a> שנכתב כ-HTML גולמי בקובץ עובר בייצוא בצד השרת כמו שנכתב: הכלל חל על קישורים ש-Markdown יוצר. בשאר הרנדררים HTML גולמי אינו מרונדר בכלל.
הכלל קובע רק איך נפתח קישור, ולא אם הכתובת נשארת קישור. את זה קובע כל מסלול בעצמו, וזה לא השתנה: בדפדפן validateLink של markdown-it, ובשרת המסנן שאחרי הרינדור. ב-_render_markdown_preview זה _is_safe_preview_url עם _LIVE_PREVIEW_ALLOWED_SCHEMES (webapp/app.py), וב-markdown_to_html זה ALLOWED_PROTOCOLS של bleach (services/styled_export_service.py). הרשימות האלה שונות זו מזו, ולכן אותה כתובת יכולה להישאר קישור במסלול אחד ולהפוך לטקסט במסלול אחר.
הבדיקות. שני העותקים של הכלל נבדקים מול אותה טבלת מקרים, tests/fixtures/md_link_target_cases.json: ``tests/md-link-target-plugin.test.js`` בודק את התוסף, ו-tests/test_md_link_target.py את צד השרת. הטסט של ה-JS בודק גם את הרינדור מול התוספים שמייצרים עוגנים, ושכל מקום שיוצר markdown-it מתקין את התוסף ושכל תבנית שמארחת רנדרר טוענת אותו. tests/test_md_link_target_browser.py לוחץ על קישור ועל עוגן בכרומיום, בעמודים האמיתיים.
כיוון של קוד בשורה ותאי טבלה
דוגמה (Markdown):
הריצו עם `--flag`, וקראו ל-`foo()`. הקובץ: `הפניות-שלא-חלו.md`, והמדריך: `מדריך-תצוגת-Markdown-RTL.md`
| שם | ערך |
|---|---|
| שפה | C++ |
| עברית | כן |
כל קוד בשורה וכל תא בטבלה מקבלים dir="auto", והדפדפן מחליט על הכיוון של כל אחד מהם לפי האות החזקה הראשונה שבו — חוץ מקוד שהוא שם קובץ עם עברית, שמקבל dir="rtl" (ראו ”שם קובץ עברי“ למטה). בדוגמה --flag ו-foo() מוצגים כמו שנכתבו; השם העברי נקרא מימין לשמאל, והסיומת משמאל לו; C++ מיושר לשמאל, ו-כן וכותרות העמודות לימין. שם הקובץ השני, שהחלק האחרון שלו לטיני, מקבל טיפול משלו — הסיומת שלו מבודדת.
למה. העמודים הם dir="rtl", וקוד בשורה ותא בטבלה ירשו את הכיוון הזה. אלגוריתם הכיווניות של הדפדפן סידר אותם לפי העברית שמסביב, וסימנים בקצה שלהם עברו לצד הלא נכון: עד נובמבר 2026 --flag הוצג flag--, foo() הוצג ()foo, ובטבלה C++ הוצג ++C ומיושר לימין. כותרת של עמודה קיבלה מהדפדפן יישור למרכז.
למה ``dir=“auto“`` ולא ``direction: ltr``. עד נובמבר 2026 קוד בשורה בפתקים הדביקים היה מבודד ב-direction: ltr עם unicode-bidi: embed (על .sticky-md-code). אותו כלל, כשהוחל על קוד בשורה בתצוגת המסמך, תיקן את אותם מקרים בדיוק, אבל הפך גם קוד שכתוב בעברית לקטע משמאל לימין: ב-הפניות-שלא-חלו.md הסיומת עברה לצד ימין, לפני השם. dir="auto" משאיר אותו בסדר הקריאה הטבעי, ומאז גם הפתקים כותבים אותו על קוד בשורה (קוד בשורה: יחידה אחת, שקודמת לכל מפריד). בתאי טבלה זו ההחלטה שהפתקים מימשו עוד קודם.
CSS. אין צורך בכלל כדי לבודד: לאלמנט עם dir הדפדפן נותן unicode-bidi: isolate מגיליון הסגנון שלו. היישור הוא text-align: start בכלל הטבלה של כל משטח — md-content-layout.css (תצוגת המסמך והתצוגה החיה), markdown-preview.css (דפדפן הריפו) ו-export/styled_document.html (הייצוא המעוצב) — ולכן כל תא מיושר לפי הכיוון שנקבע לו. יישור שהוגדר בשורת ההפרדה (---:) נכתב כ-style על התא וגובר. אין לכתוב ``direction`` על קוד בשורה או על תאים: כלל CSS כזה גובר על dir בשקט.
שם קובץ עברי שהחלק האחרון שלו לטיני: הסיומת בקצה השמאלי. ב-מדריך-תצוגת-Markdown-RTL.md הנקודה יושבת בין שתי אותיות לטיניות, והדפדפן מדביק אותה ואת הסיומת לחלק הלטיני, כך שגם עם dir="auto" הסיומת מוצגת באמצע השם, צמודה לעברית. קוד בשורה כזה מקבל dir="rtl", והסיומת נכתבת ב-<bdi> — והיא עוברת לקצה השמאלי, כמו ב-ערכות.md. זה חל גם על שם שמתחיל באנגלית, כמו Report-דוח-Q3.md. מה מפורק ומה נשאר כמו שהוא (שם בלי עברית, שם שנגמר בעברית, שם עם נקודה נוספת אחרי העברית, נתיב) — FileName.parts ב-webapp/static/js/utils/file-name.js, עם ההסבר וההחלטות; tests/file-name.test.js עובר על המקרים. הטקסט עצמו אינו משתנה, ולכן העתקה מחזירה את השם בדיוק (tests/test_md_auto_dir_browser.py מעתיק ללוח ב-Ctrl+C וקורא בחזרה), והחיפוש במסמך מוצא אותו גם כשהמחרוזת עוברת מהשם לסיומת. בפתקים הדביקים אותו פירוק נבנה כצמתים (RtlCode.fillInlineCode ב-webapp/static/js/utils/rtl-code.js).
ואותה החלטה בשמות הקבצים בממשק. רשימת הקבצים, הכותרת של עמוד הקובץ, החיפוש והצעות ההשלמה, האוספים ושולחן העבודה, הדשבורד, החיפוש בפתקים, /compare, סל המיחזור, עמוד הקבצים ששותפו בקישור ומודאל ”קבצים אחרונים“ מציגים את השם כ-<bdi>: <bdi dir="rtl"> עם הסיומת ב-<bdi> פנימי לשם שמפורק, <bdi dir="rtl"> לכל שם אחר שיש בו עברית, ו-<bdi dir="auto"> לשם בלי עברית. לא dir="auto" לכל שם: הוא בוחר כיוון לפי האות החזקה הראשונה, ובשם כמו pdf-עברי-ל-markdown-אפיון-גרסה-ראשונה.md או Handoff: שרשורי תגובות … סשן 2.md זו אות לטינית — השם יצא משמאל לימין והמילים התהפכו (כך היה בגרסה הראשונה של התיקון). ובקוד בשורה, שאינו בהכרח שם קובץ, dir="rtl" רק לקוד שנראה כמו שם קובץ — נגמר בסיומת, בלי לוכסן — ויש בו עברית (FileName.codeDir); git commit -m "הודעה" ו---flag נשארים dir="auto". כך השם גם מבודד מהטקסט שסביבו — בכרטיס תוצאת החיפוש, שהוא direction: ltr, בלי הבידוד גם ערכות.md מוצג עם הסיומת מימין לשם. ה-<bdi> נכנס בתוך האלמנט הקיים, ולכן החיתוך בשלוש נקודות וה-line-clamp שלו נשמרים. ב-JS השם נבנה ב-FileName.fill / FileName.element, רק ב-createElement ו-textContent; בעמודים שהשרת בונה — בפילטר file_name (webapp/file_name_display.py), שמחליט אותו דבר: tests/test_file_name_display.py מריץ את שני המימושים על כל תו ביוניקוד ומשווה. לכן ”עברית“ ו“לטינית“ הן טבלאות ולא \p{Script=…} — בספרייה הסטנדרטית של פייתון אין את מאפיין הכתב — וההסבר בראש utils/file-name.js. מה שאי אפשר לשים בו תגיות — title, אפשרות ברשימה נפתחת, כותרת הלשונית — נשאר כמו שהוא. test_every_visible_file_name_in_the_template_goes_through_the_filter (באותו קובץ) סורק את כל התבניות, ולא רשימה שנכתבה ביד, ונכשל על file_name בטקסט גלוי שלא עובר בפילטר: כך נמצא עמוד הקבצים המשותפים, שהמיפוי הראשון החמיץ. tests/test_file_name_display_browser.py מודד בכרומיום, עם ריצת בקרה בלי התיקון.
מקור: webapp/static/js/md-auto-dir-plugin.js — תוסף markdown-it. כל מקום שיוצר את markdown-it מתקין אותו: תצוגת המסמך (md_preview.html), הרנדרר של live-preview.js (ensureRenderer), שמשמש את ה‑Live Preview, את הייצוא המעוצב, את דפדפן הריפו ואת כרטיסי החיפוש בתיעוד, ומסלול הגיבוי של דפדפן הריפו (renderMarkdownFallback ב-repo-browser.js). ב-ensureRenderer ישב כלל code_inline משלו, שלא כתב את מאפייני הטוקן ולכן מחק את dir; הוא הוסר. מאז נובמבר 2026 התוסף עצמו מתקין כלל code_inline, שכותב את ה-<bdi> של שם קובץ עברי וקורא ל-renderAttrs, ומעביר כל קוד אחר לכלל שהיה מותקן לפניו. את הפירוק הוא קורא מ-window.RtlCode, ולכן כל תבנית שטוענת את התוסף טוענת גם את utils/rtl-code.js. ההסבר המלא, עם המקורות בספרייה ובתקן, בראש התוסף. tests/md-auto-dir-plugin.test.js שומר על ההתנהגות, ובודק שכל מקום כזה מתקין את התוסף, שכל תבנית שמארחת רנדרר טוענת אותו ואת utils/rtl-code.js לפני שמרנדרים, ושאין בוובאפ כלל code_inline שמוחק את המאפיינים. tests/test_md_auto_dir_browser.py מודד בכרומיום, בעמודים האמיתיים, את הסדר של התווים על המסך ואת היישור.
כמו המארקר, הנוסחאות והקישורים האוטומטיים, גם זה קיים רק בצד הלקוח: Reader Mode מרונדר בשרת (_render_markdown_preview ב-webapp/app.py), ואינו עובר דרך התוסף.
4. הנחיות למפתחים (Best Practices)
לא להשתמש ב‑Inline Styles בתוך Markdown.
שינוי צבעים/רקעים נעשה ב‑
reader.css(Reader Mode), ב‑markdown-enhanced.css(אדמוניציות ובלוקים מתקפלים), או ב‑md-content-colors.css— הצבעים של המסמך עצמו (#md-content): הנייר, קוד וצבעי התחביר, ציטוט, טבלה, סימון וקישורים, משותפים לתצוגת המסמך ולתצוגה החיה.שינוי פריסה של המסמך עצמו — ריווח, גדלים, שבירת שורות, בלוק הקוד ופס הכותרת שלו — נעשה ב‑
md-content-layout.css, שגם הוא משותף לשתי התצוגות. כלל שנכתב רק ב‑md_preview.htmlלא יגיע לתצוגה החיה.שמרו על התאמה בין Reader Mode ל‑Classic Theme כדי לשמר עקביות ויזואלית.
הערה
אם מוסיפים רכיב חדש, חובה לעדכן גם את מסמך ה‑Source of Truth הזה כדי ש‑QA ידע בדיוק מה אמור להופיע ובאילו קבצים.