ערכות נושא מותאמות אישית – מדריך מקיף
מבוא וסקירה כללית
מהי ערכת נושא מותאמת אישית?
ערכת נושא מותאמת אישית (Custom Theme) היא אוסף של משתני CSS המגדירים את המראה הוויזואלי של הממשק – צבעי רקע, טקסט, כפתורים, קוד ועוד.
היתרונות העיקריים:
התאמה אישית מלאה של המראה לפי טעמכם
ייבוא ערכות מ-VS Code בלחיצה אחת
שמירת מספר ערכות ומעבר ביניהן
תמיכה בהדגשת תחביר (Syntax Highlighting) ייחודית
ההבדל בין Presets לבין Custom Themes
Presets (ערכות מוכנות) |
Custom Themes (ערכות מותאמות) |
|
|---|---|---|
מקור |
מוגדרות מראש במערכת (Dark, Ocean, Classic…) |
נוצרות על ידי המשתמש או מיובאות |
עריכה |
לא ניתנות לעריכה |
ניתנות לעריכה מלאה |
הדגשת תחביר |
קבועה לפי הערכה |
מיובאת מ-VS Code או ברירת מחדל |
שמירה |
במערכת |
ב-MongoDB לפי משתמש |
יכולות המערכת
ייבוא מ-VS Code – תמיכה מלאה בפורמט JSON/JSONC של VS Code themes
יצירה ידנית – עורך צבעים מתקדם עם תצוגה מקדימה חיה
ערכות מוכנות – גלריה של ערכות פופולריות (GitHub, Dracula, Nord…)
הדגשת תחביר – מיפוי אוטומטי של
tokenColorsל-CodeMirror
ייבוא ערכות VS Code
פורמטים נתמכים
המערכת תומכת בשני פורמטי JSON:
JSON רגיל:
קובץ JSON סטנדרטי ללא הערות.
JSONC (JSON with Comments):
פורמט מורחב שתומך בהערות – נפוץ מאוד בערכות VS Code כמו Nord, One Dark Pro ועוד:
{
"name": "My Theme",
/* זו הערה מרובת שורות */
"type": "dark",
"colors": {
// זו הערה של שורה בודדת
"editor.background": "#1a1b26",
"editor.foreground": "#c0caf5",
"focusBorder": "#7aa2f7"
}
}
סוגי הערות נתמכים:
/* ... */– הערות מרובות שורות (multi-line)// ...– הערות של שורה בודדת (single-line)
הערה
המערכת מסירה אוטומטית את ההערות לפני פרסור ה-JSON, כך שאין צורך לערוך את הקובץ ידנית.
מבנה ערכת VS Code
ערכת VS Code מורכבת משלושה חלקים עיקריים:
{
"name": "Theme Name",
"type": "dark",
"colors": {
"editor.background": "#1e1e1e",
"editor.foreground": "#d4d4d4",
"button.background": "#569cd6",
"sideBar.background": "#252526"
},
"tokenColors": [
{
"scope": "comment",
"settings": {
"foreground": "#6a9955",
"fontStyle": "italic"
}
},
{
"scope": ["keyword", "storage"],
"settings": {
"foreground": "#569cd6"
}
}
]
}
הסבר השדות:
name– שם הערכהtype– סוג הערכה:"dark"או"light"(משפיע על ערכי fallback)colors– מילון של צבעי UI (רקעים, טקסט, כפתורים)tokenColors– כללי הדגשת תחביר
מיפוי צבעי UI
המערכת ממפה אוטומטית את צבעי VS Code למשתני CSS שלנו:
VS Code Key |
CSS Variable(s) |
תיאור |
|---|---|---|
|
|
רקע ראשי |
|
|
טקסט ראשי |
|
|
רקע משני |
|
|
רקע שלישוני |
|
|
כפתור ראשי |
|
|
טקסט כפתור |
|
|
כפתור בריחוף |
|
|
רקע שדה קלט |
|
|
גבול שדה קלט |
|
|
גבולות כלליים |
|
|
צבע ראשי |
|
|
צבע קישורים |
|
|
רקע קוד |
|
|
טקסט קוד |
|
|
רקע ניווט |
|
|
רקע כרטיסים |
|
|
צבע שגיאה |
|
|
צבע אזהרה |
|
|
צבע הצלחה |
יצירה ידנית (Native Format)
מבנה הפורמט המקומי
אם אתם מעדיפים ליצור ערכה מאפס, השתמשו בפורמט המקומי:
{
"name": "My Custom Theme",
"description": "ערכה מותאמת אישית",
"variables": {
"--bg-primary": "#1a1b26",
"--bg-secondary": "#24283b",
"--bg-tertiary": "#414868",
"--text-primary": "#c0caf5",
"--text-secondary": "#9aa5ce",
"--text-muted": "#565f89",
"--primary": "#7aa2f7",
"--primary-hover": "#89b4fa",
"--btn-primary-bg": "#7aa2f7",
"--btn-primary-color": "#1a1b26",
"--glass-blur": "12px"
}
}
משתנים חובה
הערכה חייבת לכלול לפחות את המשתנים הבאים לתפקוד תקין:
רקעים וטקסט (Level 2):
--bg-primary רקע ראשי של הדף
--bg-secondary רקע משני (סיידבר, כרטיסים)
--bg-tertiary רקע שלישוני (אלמנטים משניים)
--text-primary טקסט ראשי
--text-secondary טקסט משני
--text-muted טקסט מעומעם
צבעי מותג (Level 1):
--primary צבע ראשי (כפתורים, קישורים, focus)
--primary-hover צבע ראשי בריחוף
--primary-light גרסה בהירה של הצבע הראשי
כפתורים (Level 2):
--btn-primary-bg רקע כפתור ראשי
--btn-primary-color טקסט כפתור ראשי
--btn-primary-border גבול כפתור ראשי
נוספים:
--border-color צבע גבולות
--card-bg רקע כרטיסים
--input-bg רקע שדות קלט
--code-bg רקע קוד
--glass-blur טשטוש glass (בפיקסלים, למשל "12px")
רשימת משתנים מלאה (Whitelist)
חשוב
רק משתנים שנמצאים ברשימה זו נשמרים — בייבוא, ביצירה ובעדכון של ערכה אישית, ובפרסום ערכה לציבורית. משתנים שאינם ברשימה מסוננים מטעמי אבטחה.
הרשימה כאן נמשכת מהקוד, ALLOWED_VARIABLES_WHITELIST ב-services/theme_parser_service.py, בכל בנייה של התיעוד. עד נובמבר 2026 היא הייתה עותק ידני, וטוקני ה-Level 3 של ערכה מיובאת בהירה (ערכה מיובאת בהירה: שדות טופס, הדשבורד, שורת החיפוש, הכפתורים שמעל העורך ותצוגת הקוד) חסרו בו.
ALLOWED_VARIABLES_WHITELIST = frozenset([
# Level 1 - Primitives
"--primary", "--primary-hover", "--primary-light",
"--secondary",
"--success", "--warning", "--error",
"--danger-bg", "--danger-border", "--text-on-warning",
"--glass", "--glass-blur", "--glass-border", "--glass-hover",
# Level 2 - Semantic Tokens (רקעים וטקסט)
"--bg-primary", "--bg-secondary", "--bg-tertiary",
"--text-primary", "--text-secondary", "--text-muted",
"--border-color", "--shadow-color",
"--card-bg", "--card-border",
"--navbar-bg",
"--input-bg", "--input-border",
"--link-color",
"--code-bg", "--code-text", "--code-border",
# Level 2 - כפתורים (Button Tokens)
"--btn-primary-bg", "--btn-primary-color", "--btn-primary-border", "--btn-primary-shadow",
"--btn-primary-hover-bg", "--btn-primary-hover-color",
# Level 2 - Markdown & Split View
"--md-surface", "--md-text",
"--split-preview-bg", "--split-preview-meta", "--split-preview-placeholder",
# Level 2 - Markdown Enhanced (inline code, tables, mermaid)
"--md-inline-code-bg", "--md-inline-code-border", "--md-inline-code-color",
"--md-table-bg", "--md-table-border", "--md-table-header-bg",
"--md-mermaid-bg",
# Level 3 - Collections
# מאפשר לערכה בודדת לקבוע את צבע שמות הקבצים בכרטיס אוסף, בלי שהדבר
# ישפיע על ערכות אחרות. ראו את וו הדריסה ב-webapp/static/css/collections.css.
"--collections-link-override",
# Level 3 - Global Search
# מאפשר לערכה בודדת לקבוע את צבע הטקסט בהצעות ההשלמה של החיפוש הגלובלי.
# אותו מסלול בדיוק: ההצעות הן <a>, ולכן [data-theme="custom"] a צובע אותן
# ב---primary על רקע לבן קבוע. ראו את וו הדריסה ב-
# webapp/static/css/global_search.css.
"--search-suggestion-text-override",
# Level 3 - Repo Browser (Markdown preview)
# מאפשר לערכה בודדת לקבוע את הרקע ואת הגבול של בלוקי הקוד בתצוגת ה-Markdown של
# דפדפן הריפו, בלי שהדבר ישפיע על ערכות אחרות. ראו את וו הדריסה ב-
# webapp/static/css/markdown-preview.css.
"--repo-md-code-block-bg-override",
"--repo-md-code-block-border-override",
# Level 3 - Primary buttons
# מאפשר לערכה בודדת לקבוע את צבע הטקסט של כפתור primary בכל מקום שבו הוא נצבע
# היום ב---primary: כפתור שהוא <a> (דרך [data-theme="custom"] a), הכפתורים "ערוך"
# ו"העתק קוד", ומצבי פוקוס/לחיצה. ראו את וו הדריסה ב-webapp/static/css/dark-mode.css,
# בבלוק primary-btn-states-custom-type ב-webapp/templates/base.html, וב-
# webapp/templates/view_file.html.
"--btn-primary-text-override",
# Level 3 - ערכה מיובאת בהירה
# הרכיבים האלה צבועים בצבעים קבועים לרקע כהה (לבן שקוף, טקסט כמעט לבן), כמו כל ערכה
# מיובאת, ולערכה בהירה אין דרך לקבוע אותם. כל טוקן נקרא בכלל שצובע היום את הרכיב, עם
# fallback לערך שנצבע בו היום:
# - שדות טופס: .form-field ב-webapp/static/css/file-editor.css (עריכה והעלאה), וה-style
# של שדות הסינון ב-webapp/templates/files.html.
# - הפיד והפוש בדשבורד: .timeline-item, .timeline-group, .timeline-badge-*, .status-*
# ב-webapp/templates/dashboard.html.
# - שורת החיפוש בתצוגת ה-Markdown: .md-search-capsule ב-webapp/templates/md_preview.html, ובתצוגת הקוד
# .search-capsule ב-webapp/templates/view_file.html.
# - "שולחן עבודה" בעמוד הקבצים: .workspace-btn ב-webapp/templates/base.html.
# - הכפתורים שמעל העורך: .btn-switch-editor ו-.btn-editor-clip ב-webapp/static/css/codemirror-custom.css,
# ו-.md-toolbar-trigger ב-webapp/static/css/markdown-toolbar.css.
# - סרגל החיפוש ומלבני הפרטים בתצוגת הקוד: .editor-toolbar, .search-capsule, .icon-btn, .search-count,
# .divider, .fullscreen-btn ו-.meta-item ב-webapp/templates/view_file.html.
"--form-field-border-override",
"--form-field-bg-override",
"--form-field-focus-border-override",
"--timeline-block-bg-override",
"--timeline-item-border-override",
"--timeline-badge-text-override",
"--status-pill-text-override",
"--md-search-capsule-border-override",
"--workspace-btn-bg-override",
"--workspace-btn-border-override",
"--editor-btn-text-override",
"--editor-btn-bg-override",
"--editor-btn-border-override",
"--editor-btn-hover-bg-override",
"--editor-switch-btn-bg-override",
"--editor-switch-btn-hover-bg-override",
"--code-toolbar-bg-override",
"--code-toolbar-border-override",
"--code-toolbar-hover-bg-override",
"--code-toolbar-text-override",
"--code-search-capsule-bg-override",
"--code-search-capsule-focus-border-override",
"--file-meta-item-bg-override",
# Level 3 - צבעי המסמך (תצוגת ה-Markdown והתצוגה החיה)
# התצוגה המרונדרת של VS Code צובעת כותרות והדגשה ב-editor.foreground, בלי מפתח משלהן, ולכן אין להם מקור
# בקובץ ערכה: ערכה בודדת מצהירה עליהם בבלוק variables שלה. ראו את וו הדריסה ב-
# webapp/static/css/md-content-colors.css ("צבעי המסמך" וכלל הציטוט).
"--md-heading-color-override",
"--md-subheading-color-override",
"--md-strong-color-override",
"--md-inline-code-color-override",
"--md-blockquote-border-override",
# Level 3 - שם הקובץ ותיאורו (כרטיס הקובץ בעמוד הקבצים, ובראש תצוגת הקוד, ה-Markdown וה-HTML)
# בערכה מיובאת השם נצבע בכלל הכותרות של dark-mode.css, התיאור בכלל הפסקאות, והשורות, הגודל והתאריכים
# בכרטיס יורשים את צבע הטקסט — כלומר הכול באותו צבע כשהערכה נותנת ל---text-primary ול---text-secondary
# אותו ערך. ערכה בודדת מצהירה על צבעים לשם, לתיאור ולמטא בבלוק variables שלה. ראו את וו הדריסה ב-
# webapp/static/css/dark-mode.css (.file-name-text, .file-description-text, .file-card-meta).
"--file-name-color-override",
"--file-description-color-override",
"--file-card-meta-color-override",
])
דריסת טוקן שאין לו מקבילה ב-VS Code
חלק מהטוקנים אינם נגזרים משום מפתח של VS Code, כי אין להם מקבילה שם. --collections-link-override הוא כזה: הוא צובע את שמות הקבצים בדף /collections — גם בכרטיס אוסף וגם בשולחן העבודה, שני מסכים נפרדים שמרנדרים את אותו סוג קישור. בכוונה אין לו ערך ברירת מחדל בשום מקום, ולכן ה-CSS נופל לערך שנצבע היום כשהערכה אינה מצהירה עליו.
בערכה מיובאת שאינה מצהירה עליו, שמות הקבצים מקבלים את --primary של הערכה. זה נכון לרוב הערכות, אבל כרטיס האוסף נשאר לבן גם בערכות כהות — ולכן ערכה שה---primary שלה בהיר מקבלת טקסט בהיר על רקע בהיר.
כדי לפתור את זה בערכה בודדת, בלי להשפיע על שאר הערכות, אפשר להוסיף בלוק variables לצד colors באותו קובץ VS Code:
{
"name": "Cobalt Next",
"type": "dark",
"colors": {
"editor.background": "#1b2b34",
"editor.foreground": "#d8dee9",
"focusBorder": "#ffffff"
},
"tokenColors": [],
"variables": {
"--collections-link-override": "#2e6161"
}
}
הבלוק עובר את אותה ולידציה ואת אותה רשימה לבנה כמו כל שאר הטוקנים — ערך שאינו צבע תקין מוחזר עם 400 ומציין את המפתח, ולא נזרק בשקט — ומתמזג מעל התוצאה שנגזרה מ-colors. tokenColors ממשיך להיות מעובד כרגיל, ולכן הדגשת התחביר אינה נפגעת. שימו לב ש-colors חייב להכיל לפחות שלושה מפתחות, אחרת הייבוא נדחה.
הערה
ערכה שאינה מצהירה על הטוקן מרונדרת ללא כל שינוי, בשני המצבים: webapp/static/css/collections.css נופל ל-var(--primary) במצב רגיל ול-var(--primary-dark) ב-:hover — בדיוק הערכים שנצבעו גם קודם. זו דריסה בהצטרפות מרצון, לא שינוי גורף.
הצעות ההשלמה בחיפוש הגלובלי
--search-suggestion-text-override הוא וו מאותו סוג בדיוק, ובאותו מסלול שורש. ההצעות שקופצות מתחת לתיבת החיפוש הגלובלי מרונדרות ב-webapp/static/js/global_search.js כאלמנטי <a>, ולכן [data-theme="custom"] a שב-dark-mode.css צובע אותן ב-var(--primary) — ספציפיות שגוברת על כלל המחלקה שב-global_search.css. רקע התיבה, לעומת זאת, אינו של הערכה כלל: הוא --solid-surface-bg, שנשאר לבן בכל ערכה. כלומר צבע הטקסט נגזר מהערכה והרקע לא, והניגודיות יוצאת מקרית — ערכה שה---primary שלה לבן מקבלת טקסט לבן על רקע לבן.
ההצהרה נראית זהה, ושני הטוקנים יכולים לחיות באותו בלוק:
"variables": {
"--collections-link-override": "#2e6161",
"--search-suggestion-text-override": "#2e6161"
}
הערה
כאן יש שלושה מצבים ולא שניים, ולכל אחד var() משלו ב-webapp/static/css/global_search.css: המצב הרגיל נופל ל-var(--primary), :hover נופל ל-var(--primary-dark), ו-:focus-visible נופל ל-var(--suggestions-text). השלישי אינו טעות: .search-suggestion:focus-visible מנצח כבר היום את כלל ה-<a> בזכות ספציפיות, ולכן הערך שנצבע בו היום שונה משני האחרים. ערכה שאינה מצהירה מרונדרת זהה לחלוטין בשלושת המצבים.
אזהרה
הערך נשמר ב-MongoDB בזמן הייבוא. ערכה שכבר קיימת בחשבון אינה מכירה טוקן שנוסף אחריה — צריך לייבא אותה מחדש. זו הסיבה הראשונה לבדוק כשההצהרה נוספה ולא נראה שינוי.
בלוקי הקוד בתצוגת ה-Markdown של דפדפן הריפו
--repo-md-code-block-bg-override ו---repo-md-code-block-border-override הם שני ווים מאותו סוג, לרקע ולגבול של בלוקי הקוד בתצוגת ה-Markdown של דפדפן הריפו. בערכה מיובאת, webapp/static/css/markdown-preview.css צובע את המעטפת של התצוגה ב---bg-tertiary, את הבלוק ב---code-bg ואת הגבול שלו ב---border-color. VSCODE_TO_CSS_MAP גוזר כל אחד מהשלושה ממפתחות אחרים של VS Code, ולכן ערכה שבה שלושתם יוצאים באותו צבע מקבלת בלוק שאינו נבדל מהטקסט שסביבו — בלי רקע אחר ובלי גבול נראה. כך קורה ב-Cobalt Next.
הדריסה היא בשני טוקנים חדשים ולא ב---code-bg עצמו, כי --code-bg צובע גם רכיבי קוד אחרים — למשל את תצוגת הקוד ב-/file ואת קטעי הקוד בחיפוש הגלובלי — ודריסה שלו בערכה הייתה משנה גם אותם. ההצהרה נראית זהה לשני הווים הקודמים, וכולם יכולים לחיות באותו בלוק:
"variables": {
"--collections-link-override": "#2e6161",
"--search-suggestion-text-override": "#2e6161",
"--repo-md-code-block-bg-override": "#21313a",
"--repo-md-code-block-border-override": "#374751"
}
הערה
ערכה שאינה מצהירה על הטוקנים מרונדרת ללא שינוי: הרקע נופל ל-var(--code-bg, var(--bg-secondary, #1e1e1e)) והגבול ל-var(--md-preview-border) — הטוקן של התצוגה, שקורא את --border-color של הערכה — מה שנצבע שם גם קודם. שני הטוקנים נקראים בכלל הקיים שצובע את הבלוק בערכות מיובאות ומשותפות, ולא בכלל חדש, כך שהמפל של ערכה שאינה מצהירה נשאר זהה. הגבול נקבע ב-border-color בלבד, והעובי והסגנון נשארים של הכלל הכללי .markdown-preview-content pre. tests/services/test_theme_variables_repo_md_code_block_hook.py נועל את החוזה הזה. וגם כאן, ערכה שכבר קיימת בחשבון מקבלת את הטוקנים רק אחרי ייבוא מחדש.
הטקסט בכפתורי primary
--btn-primary-text-override הוא וו מאותו סוג, לצבע הטקסט של כפתור primary. בערכה מיובאת או משותפת הטקסט הזה נצבע ב---primary בכמה מקומות:
כפתור שהוא קישור,
<a class="btn btn-primary">— למשל הלשונית הנבחרת בעמוד הקבצים והכפתורים בעמוד ההגדרות — נצבע דרך[data-theme="custom"] aשב-webapp/static/css/dark-mode.css, ובריחוף דרךa:hoverשם, ב---primary-dark.”ערוך“ ו“העתק קוד“ בעמוד הקובץ נצבעים דרך
.file-primary-actionשב-webapp/templates/view_file.html, גם בריחוף.מצבי הפוקוס, הלחיצה וההשבתה של כל כפתור primary, וכל כפתור primary בערכה משותפת, נצבעים דרך כללי ה-
!importantשבבלוקprimary-btn-states-custom-typeב-webapp/templates/base.html.
--primary נגזר ממפתחות VS Code אחרים מאלה שקובעים את רקע הכפתור (button.background), ולכן השניים יכולים לצאת קרובים. ב-Everforest Dark --primary הוא #7fbbb3 — notificationsInfoIcon.foreground ממופה אליו אחרי focusBorder ב-VSCODE_TO_CSS_MAP, ולכן הוא שקובע — על רקע #a7c080, כלומר ניגודיות 1.09 לפי WCAG. כפתור primary שהוא <button>, כמו ”חפש“, אינו מושפע במצב רגיל: הוא נצבע ב---btn-primary-color, שהערכה קובעת דרך button.foreground.
{
"name": "Everforest Dark",
"type": "dark",
"colors": {
"editor.background": "#2d353b",
"button.background": "#a7c080",
"button.foreground": "#2d353b",
"focusBorder": "#2d353b00",
"notificationsInfoIcon.foreground": "#7fbbb3"
},
"tokenColors": [],
"variables": {
"--btn-primary-text-override": "#232a2e"
}
}
הערה
ערכה שאינה מצהירה על הטוקן מרונדרת ללא שינוי, בכל מצב: כל כלל נופל לערך שהוא צבע עד היום — var(--primary), ובריחוף של קישור var(--primary-dark). בכללים הקיימים הטוקן נקרא בלי לשנות את הבורר. לקישורים נוספו ב-dark-mode.css שני כללים, רגיל וריחוף, עם הבוררים של כללי הקישורים עצמם ועם :where(.btn-primary): :where() אינו מוסיף ספציפיות, והכללים כתובים מיד אחרי כללי הקישורים, ולכן הם חלים בדיוק במקום שבו כללי הקישורים צובעים היום. הבורר הוא [data-theme="custom"] ולא [data-theme-type="custom"], בכוונה: סנכרון הערכה בין טאבים (initThemeCrossTabSync ב-base.html) מחליף את data-theme לערכה מובנית שנבחרה בטאב אחר ומשאיר את data-theme-type, וכלל שנשען עליו היה ממשיך לחול בטאב הזה על הערכה המובנית. tests/services/test_theme_variables_btn_primary_text_hook.py נועל את החוזה, וגם כאן ערכה שכבר קיימת בחשבון מקבלת את הטוקן רק אחרי ייבוא מחדש.
ערכה מיובאת בהירה: שדות טופס, הדשבורד, שורת החיפוש, הכפתורים שמעל העורך ותצוגת הקוד
כל ערכה מיובאת מקבלת את העיצוב של הערכות הכהות, וזה נשאר כך בכוונה. כמה רכיבים צבועים שם בצבעים קבועים לרקע כהה — לבן שקוף לגבולות ולרקעים, וטקסט לבן או כמעט לבן בתגים ובכפתורים — ולכן בערכה מיובאת בהירה הם לא נראים. לערכות המובנות הבהירות יש לחלק מהם כללים משלהן, ולערכה מיובאת אין. ווים מאותו סוג נותנים לערכה בהירה לקבוע אותם לעצמה:
--form-field-border-override,--form-field-bg-overrideו---form-field-focus-border-override— הגבול, הרקע והגבול בפוקוס של השדות בעמודי העריכה וההעלאה (.form-fieldב-webapp/static/css/file-editor.css): שם הקובץ, השפה, התיאור, התגיות והקוד. שני הראשונים נקראים גם בשדות הסינון בעמוד הקבצים (החיפוש, השפה והמיון), שצבועים רק ב-styleשבתגית שלהם ב-webapp/templates/files.html.--timeline-block-bg-override— הרקע של הבלוקים בפיד האחרון בדשבורד: הקבוצה (.timeline-group) והפריט שבתוכה (.timeline-item), שצבועים היום באותו ערך.--timeline-item-border-override— הפס בצד של כל פריט.--timeline-badge-text-override— הטקסט של התג בפיד, בכל סוגי התג (.timeline-badge-code,-info,-warningו--neutral). הרקע של כל סוג נשאר בגוון שלו.--status-pill-text-override— הטקסט של הבאדג« בכרטיס הגדרות הפוש (”מופעל ב-X דפדפנים“), בכל סוגי הבאדג« (.status-success,-warning,-dangerו--neutral).--md-search-capsule-border-override— הגבול של שורת החיפוש, שהוא שקוף עד שמתחילים להקליד: בתצוגת ה-Markdown (.md-search-capsuleב-webapp/templates/md_preview.html) ובתצוגת הקוד (.search-capsuleב-webapp/templates/view_file.html). זה אותו רכיב בשני עותקים, ולכן אותו וו.--workspace-btn-bg-overrideו---workspace-btn-border-override— ”שולחן עבודה“ בעמוד הקבצים (.workspace-btnב-webapp/templates/base.html). הרקע שלו הוא מעבר צבע מ---primaryל---secondary, ו---secondaryאינו ב-VSCODE_TO_CSS_MAP, ולכן בערכה מיובאת מעבר הצבע מסתיים בערך הקבוע שבבלוק ה-:rootשלbase.html. הראשון מחליף את מעבר הצבע ברקע אחיד, והשני מוסיף מסגרת של פיקסל. המסגרת היאbox-shadowולאborder, כי גבול היה מגדיל את הכפתור גם בערכה שאינה מצהירה; ההערה מעל הכלל ב-base.htmlמסבירה איך היא נשארתnoneבערכה כזו. הטקסט אינו נקבע כאן: בערכה מיובאת הוא נצבע, כמו בשאר הכפתורים שהם קישורים, בכלל[data-theme="custom"] aשב-webapp/static/css/dark-mode.css.--editor-btn-text-override,--editor-btn-bg-override,--editor-btn-border-overrideו---editor-btn-hover-bg-override— הכפתורים שמעל העורך, בכל עמוד שיש בו את הסרגל שלaddSwitcherButton(webapp/static/js/editor-manager.js): ”בטל“, ”בצע שוב“, ”בחר הכל“, ”העתק“ ו“הדבק“ (.btn-editor-clipב-webapp/static/css/codemirror-custom.css). הטקסט והגבול נקראים גם ב-”עורך פשוט“ / ”עורך מתקדם“ (.btn-switch-editor), והטקסט גם בכפתור ה-MD (.md-toolbar-triggerב-webapp/static/css/markdown-toolbar.css). בערכה שמצהירה על--editor-btn-border-override, הגבול של.btn-editor-clipבריחוף הוא אותו גבול כמו במצב הרגיל.--editor-switch-btn-bg-overrideו---editor-switch-btn-hover-bg-override— הרקע של ”עורך פשוט“ / ”עורך מתקדם“, רגיל ובריחוף, כדי שהכפתור יוכל להישאר מובחן משאר הכפתורים בשורה.--code-toolbar-bg-override,--code-toolbar-border-override,--code-toolbar-hover-bg-overrideו---code-toolbar-text-override— סרגל החיפוש בתצוגת הקוד (.editor-toolbarב-webapp/templates/view_file.html): הרקע והגבול של הסרגל ושל ”מסך מלא“ (.fullscreen-btn), גם בריחוף; הקו המפריד בשורת החיפוש (.divider), בצבע הגבול; הרקע בריחוף של ”מסך מלא“ ושל ▲ ▼ ✕ (.icon-btn); והצבע של ▲ ▼ ✕ ושל מונה התוצאות (.search-count). בתצוגת ה-Markdown אותו סרגל (.md-editor-toolbar) צבוע ב---glassוב---glass-borderשל הערכה, ולכן שם אין צורך בווים.--code-search-capsule-bg-override— הרקע של שורת החיפוש בתצוגת הקוד (.search-capsule), גם בזמן הקלדה.--code-search-capsule-focus-border-override— הגבול שלה בזמן הקלדה (.search-capsule:focus-within).--file-meta-item-bg-override— המלבנים של גודל, שורות, נוצר ועודכן בתצוגת הקוד (.meta-itemב-view_file.html).
{
"name": "Pen Paper Coffee UI",
"type": "light",
"colors": {
"editor.background": "#f8f6f1",
"editor.foreground": "#2b3f6a",
"editorWidget.background": "#ebe8df"
},
"tokenColors": [],
"variables": {
"--form-field-border-override": "rgba(110, 78, 68, 0.35)",
"--form-field-bg-override": "rgba(255, 253, 249, 0.6)",
"--form-field-focus-border-override": "#6e4e44",
"--timeline-block-bg-override": "rgba(110, 78, 68, 0.06)",
"--timeline-item-border-override": "rgba(110, 78, 68, 0.35)",
"--timeline-badge-text-override": "#2b3f6a",
"--status-pill-text-override": "#2b3f6a",
"--md-search-capsule-border-override": "rgba(110, 78, 68, 0.3)",
"--workspace-btn-bg-override": "rgba(224, 218, 211, 0.55)",
"--workspace-btn-border-override": "rgba(110, 78, 68, 0.3)",
"--editor-btn-text-override": "#2b3f6a",
"--editor-btn-bg-override": "rgba(255, 253, 249, 0.6)",
"--editor-btn-border-override": "rgba(110, 78, 68, 0.3)",
"--editor-btn-hover-bg-override": "rgba(110, 78, 68, 0.12)",
"--editor-switch-btn-bg-override": "#e4dcc8",
"--editor-switch-btn-hover-bg-override": "#d2b493",
"--code-toolbar-bg-override": "rgba(224, 218, 211, 0.55)",
"--code-toolbar-border-override": "rgba(110, 78, 68, 0.3)",
"--code-toolbar-hover-bg-override": "rgba(110, 78, 68, 0.12)",
"--code-toolbar-text-override": "#2b3f6a",
"--code-search-capsule-bg-override": "rgba(248, 246, 241, 0.25)",
"--code-search-capsule-focus-border-override": "#6e4e44",
"--file-meta-item-bg-override": "rgba(255, 253, 249, 0.6)"
}
}
הערה
ערכה שאינה מצהירה על הטוקנים מרונדרת ללא שינוי, וכך גם התצוגה המקדימה של ערכה מובנית מתוך אשף הערכות: כל טוקן נקרא בכלל שצובע היום את הרכיב, עם fallback לערך שנצבע בו, והבורר של הכלל לא השתנה. במקומות שבהם ל-Rose Pine Dawn יש כלל משלה — השדות בעמודי העריכה וההעלאה, הפיד והפוש, שורת החיפוש בתצוגת ה-Markdown, הכפתורים שמעל העורך ו“מסך מלא“ — הכלל שלה ספציפי יותר וממשיך לגבור. בשורת החיפוש של תצוגת ה-Markdown ה-fallback הוא transparent, הגבול של הכלל הכללי, וכלל ה-:focus-within ספציפי יותר מהכלל שקורא את הווו, ולכן בזמן הקלדה הגבול נשאר שלו. בתצוגת הקוד כלל ה-:focus-within קורא וו משלו, --code-search-capsule-focus-border-override. ב“שולחן עבודה“ הריחוף נשאר כמו שהוא, כמו בשאר הכפתורים בשורה: הרקע מגיע מ-.btn-secondary:hover, וה-box-shadow מ-.categories-section .btn:hover ב-webapp/templates/files.html, שספציפי יותר מהכלל של המסגרת ולכן מחליף אותה בזמן הריחוף. tests/services/test_theme_variables_light_import_hooks.py נועל את החוזה, כולל הדוגמה שלמעלה, וגם כאן ערכה שכבר קיימת בחשבון מקבלת את הטוקנים רק אחרי ייבוא מחדש. מה נמדד ב-31.10.2026, על הדוגמה שלמעלה עם הרקע של Pen Paper Coffee, מול הפיקסל האמיתי שמאחורי כל רכיב: הטקסט בתגים ובבאדג« עלה מניגודיות של 1.18–1.35 ל-5.75–7.18, והגבול של השדות מ-1.06 ל-1.51. בערכות שאינן מצהירות — Classic, Dark, Rose Pine Dawn, High Contrast, ערכה מיובאת כהה וערכה מיובאת בהירה — הרכיבים זהים למה שהיו לפני הווים, גם בפוקוס ובתצוגה המקדימה. ומה נמדד ב-15.11.2026, כשנוספו הווים של ”שולחן עבודה“, הכפתורים שמעל העורך ותצוגת הקוד, בדפדפן ומול הקוד שלפני השינוי: בערכות שאינן מצהירות — Classic, Dark, Rose Pine Dawn, High Contrast, ערכה מיובאת כהה וערכה מיובאת בהירה בלי ווים — ובתצוגה מקדימה של Ocean מתוך ערכה שמצהירה, כל הרכיבים האלה זהים למה שהיו, במצב רגיל, בריחוף ובפוקוס.
צבעי המסמך: כותרות, הדגשה, קוד בשורה וציטוט
בתצוגת ה-Markdown (md_preview.html) ובתצוגה החיה בעמודי העריכה וההעלאה, ערכה מיובאת מבדילה בין חלקי המסמך רק בשני צבעי טקסט: כותרות ורשימות ב---text-primary (מ-editor.foreground, ו-input.foreground דורס אותו כשהוא בקובץ), ופסקאות — גם בתוך ציטוט — ב---text-secondary (מ-sideBar.foreground), בכלל ה-Typography של webapp/static/css/dark-mode.css שצובע כל p, ולא בירושה מ-#md-content. כששני המפתחות זהים בקובץ, כמו ב-morass, כל המסמך יוצא בצבע אחד.
אין לזה מקור בקובץ הערכה. התצוגה המרונדרת של VS Code עצמו צובעת כותרות והדגשה ב-editor.foreground, בלי מפתח משלהן; רק לקישור (textLink.foreground), לקוד בשורה (textPreformat.foreground), לציטוט (textBlockQuote.background / textBlockQuote.border) ולבלוק קוד (textCodeBlock.background) יש מפתח — נקרא ב-microsoft/vscode@864824b4, בקבצים src/vs/workbench/contrib/webview/browser/pre/index.html ו-extensions/markdown-language-features/media/markdown.css. markup.heading, markup.bold ושכניהם ב-tokenColors אינם צבעי המסמך: הם צובעים את מקור ה-Markdown בעורך, דרך הדקדוק של TextMate, ובמערכת שלנו הם הופכים להדגשת תחביר בבלוקי קוד (הדגשת התחביר בפרסום).
לכן אלה ווים מאותו סוג של הקודמים: ערכה בודדת שרוצה מסמך צבעוני מצהירה עליהם בבלוק variables, וערכה שאינה מצהירה נשארת כמו היום. הם נקראים ב-webapp/static/css/md-content-colors.css, בכללים שחלים רק בתוך #md-content ורק בערכה מיובאת או משותפת:
--md-heading-color-override— כותרות H1 ו-H2. בלעדיו:--text-primary.--md-subheading-color-override— כותרות H3 עד H6. בלעדיו:--text-primary.--md-strong-color-override— הדגשה (strongו-b), גם בתוך רשימה וציטוט. בלעדיו: הצבע שההדגשה יורשת מהטקסט שסביבה.--md-inline-code-color-override— קוד בשורה. בלעדיו:--code-text(מ-terminal.foreground).--md-blockquote-border-override— הפס של הציטוט. בלעדיו:--md-blockquote-border, צבע הטקסט בשקיפות.לקישור אין טוקן חדש: הוא כבר נקרא מ-
--link-color, ובערכה שאין בהtextLink.foregroundאפשר להצהיר עליו באותו בלוק.
הדוגמה של morass — הצבעים שנבחרו לה מתוך הצבעים שכבר יש בקובץ שלה, וגם --primary רך יותר מה-focusBorder שהמייבא גוזר:
"variables": {
"--primary": "#E1C636",
"--md-heading-color-override": "#E1C636",
"--md-subheading-color-override": "#cfd394",
"--md-strong-color-override": "#dcdcaa",
"--link-color": "#7fdbca",
"--md-inline-code-color-override": "#b5cea8",
"--md-blockquote-border-override": "#E1C636"
}
הערה
ערכה שאינה מצהירה על הטוקנים מרונדרת ללא שינוי. הקוד בשורה והציטוט נקראים בכללים שצובעים אותם היום, ו-fallback של כל טוקן הוא הערך שנצבע שם. לכותרות ולהדגשה אין במסמך כלל משלהן: הכותרות נצבעות היום בכלל ה-Typography של webapp/static/css/dark-mode.css, שחל על כל כותרת באתר, וההדגשה יורשת את צבע הטקסט שסביבה. לכן נוספו להן כללים שחלים רק בתוך #md-content — לכותרות עם fallback לאותו --text-primary, ולהדגשה עם fallback ל-inherit. כותרות בממשק, מחוץ למסמך, לא מושפעות. tests/services/test_theme_variables_md_document_colors_hook.py נועל את החוזה, ו-tests/test_md_document_colors_hook_browser.py מודד בדפדפן את שתי התצוגות, בערכה אישית ובערכה שפורסמה לציבורית. מצבי הרקע של תצוגת המסמך (ספיה ושאר הגוונים) לא חלים כאן: הם מוצעים רק בערכות מובנות בהירות (ALLOWED_THEMES ב-md_preview.html). וכמו בכל וו, ערכה שכבר קיימת בחשבון מקבלת את הטוקנים רק אחרי ייבוא מחדש, וערכה ציבורית — אחרי פרסום מחדש.
שם הקובץ ותיאורו: כרטיס הקובץ ותצוגות הקובץ
שם הקובץ מוצג ככותרת בכרטיס הקובץ בעמוד הקבצים, ובראש תצוגת הקוד (/file/<id>), תצוגת ה-Markdown (/md/<id>) ותצוגת ה-HTML (/html/<id>). בערכה מיובאת או משותפת הוא נצבע בכלל ה-Typography של webapp/static/css/dark-mode.css שצובע כל כותרת, ב---text-primary. התיאור — בכרטיס ובתצוגת הקוד; לשתי התצוגות האחרות אין תיאור — נצבע בכלל הפסקאות שם, ב---text-secondary. והשורות, הגודל והתאריכים בכרטיס לא נצבעים בשום כלל: הם יורשים את צבע הטקסט. כש-editor.foreground ו-sideBar.foreground זהים בקובץ, כמו ב-morass, כל הכרטיס יוצא בצבע אחד.
גם כאן אלה ווים מאותו סוג: ערכה בודדת מצהירה על צבעים בבלוק variables, וערכה שאינה מצהירה נשארת כמו היום. הם נקראים ב-dark-mode.css, בכללים שחלים רק בערכה מיובאת או משותפת, על class שנמצא על האלמנט שמציג את השם או את התיאור בכל אחד מהעמודים:
--file-name-color-override— שם הקובץ (.file-name-text), בכרטיס ובשלוש התצוגות. בתצוגת ה-HTML השם הוא חלק מהכותרת ”תצוגת דפדפן: <שם>“, וה-class נמצא רק על השם: התחילית נשארת בצבע של הכותרת. בלעדיו:--text-primary.--file-description-color-override— התיאור (.file-description-text), בכרטיס ובתצוגת הקוד. בלעדיו:--text-secondary.--file-card-meta-color-override— השורות, הגודל והתאריכים בכרטיס (.file-card-meta), כולל האייקונים של התאריכים. בלעדיו: הצבע שהם יורשים. השקיפות שלהם נקבעת ב-styleשבתגית ב-webapp/templates/files.htmlונשארת, ולכן הצבע שנבחר נראה על הכרטיס כהה מהערך שבבלוק — את הניגודיות כדאי לבדוק אחרי השקיפות.התגיות וכפתורי הפעולה בכרטיס לא מושפעים.
הדוגמה של morass — בז« לשם, ירוק חיוור למטא, והתיאור ב-#e4e3e1, צבע הטקסט של הערכה, כלומר כמו היום:
"variables": {
"--file-name-color-override": "#dcdcaa",
"--file-description-color-override": "#e4e3e1",
"--file-card-meta-color-override": "#b5cea8"
}
הערה
ערכה שאינה מצהירה על הטוקנים מרונדרת ללא שינוי: ה-fallback של השם הוא ה---text-primary של כלל הכותרות, של התיאור ה---text-secondary של כלל הפסקאות, ושל המטא inherit. הבורר ([data-theme="custom"] .file-name-text ושכניו) ספציפי יותר מכללי ה-Typography, ולכן הוא גובר עליהם בלי תלות בסדר. הוא [data-theme="custom"] ולא [data-theme-type="custom"], מאותה סיבה כמו בכפתורי primary: סנכרון הערכה בין טאבים (initThemeCrossTabSync ב-base.html) מחליף את data-theme לערכה מובנית שנבחרה בטאב אחר ומשאיר את data-theme-type, וכלל שנשען עליו היה ממשיך לחול בטאב הזה על הערכה המובנית. בערכה מובנית ה-class אינו משנה דבר. tests/services/test_theme_variables_file_name_hook.py נועל את החוזה — כולל שה-class נמצא בכל תבנית על האלמנט שהטקסט שלו הוא השם או התיאור — ורץ גם בלי דפדפן; tests/test_file_name_colors_hook_browser.py מודד בדפדפן את ארבעת העמודים, בערכה אישית, בערכה שפורסמה לציבורית ובערכות מובנות. וכמו בכל וו, ערכה שכבר קיימת בחשבון מקבלת את הטוקנים רק אחרי ייבוא מחדש, וערכה ציבורית — אחרי פרסום מחדש.
ערכת מסמך: ערכה שחלה רק על תצוגת ה-Markdown
יש ערכות שנראות מצוין במסמך ופחות טוב בשאר הממשק — למשל ערכה בהירה בגוון נייר. ערכת מסמך מחילה ערכה כזו רק על הכרטיס ”תצוגת Markdown“ בעמוד /md/<id> (#mdCard ב-webapp/templates/md_preview.html), והממשק סביבו נשאר בערכה הפעילה: דף נייר בהיר על שולחן כהה. הכרטיס כולו עובר — הכותרת ”תצוגת Markdown“, שורת החיפוש, הכפתורים שבו והמסמך עצמו, כולל קוד בשורה, בלוקי קוד והדגשת התחביר שלהם, ציטוטים, טבלאות, הקטעים המתקפלים והדיאגרמות. מה שמעליו — סרגל הניווט, שם הקובץ והכפתורים ”חזרה“ ו“ערוך“ — נשאר בערכת הממשק.
איפה בוחרים. בשני מקומות. בגלריית הערכות (/settings/theme-gallery), בלשונית ”ייבוא“: התיבה ”ערכת המסמך“ מציגה מה פעיל, ובוחרים בה ערכה אישית או ציבורית, או ”ללא ערכת מסמך“ כדי לכבות. ליד הייבוא יש תיבת סימון ”להחיל את הערכה שמייבאים רק על תצוגת המסמך“: אחרי ייבוא מוצלח הערכה החדשה נבחרת כערכת המסמך. מסלול הייבוא עצמו (POST /api/themes/import) לא השתנה — הבחירה היא קריאה שנייה, ל-/api/ui_prefs.
ובכל עמוד — במודאל ערכות הנושא שנפתח מתפריט קיצורי הדרך (”ערכת נושא“), דרך המתג ”ערכת ממשק / ערכת מסמך“ שבראשו. במצב ”ערכת מסמך“ הרשת מציגה את הכרטיס ”ללא ערכת מסמך“ ואחריו רק ערכות אישיות וציבוריות (הטאב ”מובנות“ מוסתר); הכרטיס של ערכת המסמך הנוכחית מסומן, ולחיצה על כרטיס אחר הופכת אותו לערכת המסמך, או מכבה אותה. עד שהשמירה חוזרת כל הכרטיסים נעולים (docSaving ב-initThemePicker): בחירה שנייה הייתה נבדקת מול הבחירה הקודמת, שעוד לא התעדכנה, ושתי שמירות במקביל היו מסתיימות בסדר שאין עליו שליטה. כשערכת הממשק מובנית מופיעה הערה שהבחירה נשמרת אבל רדומה (ראו ”מתי היא חלה“ למטה); התנאי שהמודאל בודק הוא MD_DOC_THEME_UI_CONDITION, החצי של MD_DOC_THEME_ROOT_SELECTOR שעוסק בערכת הממשק. בעמוד מסמך, כשערכת המסמך חלה, העמוד נטען מחדש כדי שהכרטיס יקבל אותה; בכל עמוד אחר הרשת פשוט מתעדכנת. הבחירה נשמרת בתחולה שמוגדרת במכשיר (ה-cookie MD_DOC_THEME_SCOPE_COOKIE, ולכל המכשירים כשאין), כך שבחירה ”רק במכשיר הזה“ נשארת במכשיר. כל פתיחה של המודאל מתחילה ב“ערכת ממשק“, שהיא המודאל כמו שהיה.
מתי היא חלה. רק כשערכת הממשק מותאמת או ציבורית. בערכה מובנית (Classic, Nebula, ניגודיות גבוהה ושאר המובנות) הבחירה נשמרת אבל רדומה, והכרטיס בערכת הממשק: הכללים שהערכות המובנות מחילות על הכרטיס שונים מאלה של ערכה מותאמת, ולא רק במשתנים, ולכן משתני ערכת המסמך לבדם לא היו צובעים אותו כמו כשהיא ערכת הממשק. ניגודיות גבוהה היא ערכת נגישות שכופה צבעים בכוונה, ולכן גם לא הייתה אמורה לקבל ערכה אחרת. התנאי כתוב בבורר אחד, MD_DOC_THEME_ROOT_SELECTOR ב-services/theme_parser_service.py, והוא בודק את data-theme ולא את data-theme-type, מאותה סיבה כמו בווי הדריסה (סנכרון הערכה בין טאבים).
איפה נשמרת הבחירה. ui_prefs.md_doc_theme במסמך המשתמש, בפורמט של ui_prefs.theme: custom:<id> לערכה אישית, shared:<slug> לציבורית, ושדה חסר כשאין ערכת מסמך. זה מצביע לערכה ולא העתק שלה, ולכן עריכה של הערכה בבונה הערכות מגיעה למסמך מעצמה. כמו גודל הטקסט בפתק, אפשר לבחור ”רק במכשיר הזה“: אז הבחירה ב-cookie ui_md_doc_theme ולא במסד, וכיבוי במכשיר נשמר שם כ-MD_DOC_THEME_DEVICE_OFF — כך הוא גובר על בחירה ששמורה במסד. ההכרעה ב-_resolve_md_doc_theme_token (webapp/app.py). מחיקת ערכה אישית מוחקת גם את ui_prefs.md_doc_theme כשהוא מצביע עליה; מצביע שנשאר — ב-cookie של מכשיר אחר, או לערכה ציבורית שכובתה — לא מוצא ערכה, והמסמך מוצג בערכת הממשק.
השמירה. POST /api/ui_prefs עם md_doc_theme (טוקן, או null לכיבוי) ו-md_doc_theme_scope (global / device). ערך שאינו טוקן תקין ← 400, ערכה שלא קיימת ← 404 md_doc_theme_not_found, ומסד שלא ענה ← 503 database_unavailable — כך ”לא נמצא“ ו“נשבר“ לא נראים אותו דבר. במצב global התשובה היא מה שנקרא מהמסד אחרי הכתיבה, ולא מה שנשלח.
הבחירה הנוכחית. שני המסכים קוראים אותה מ-GET /api/ui_prefs/md_doc_theme (api_md_doc_theme_state), ולא מה-HTML של העמוד: המודאל נמצא בכל עמוד, ומצב שמרונדר לתוך ה-HTML היה צריך להיכנס למפתח הקאש ול-ETag של כל עמוד ששומר HTML. התשובה היא ההכרעה של _resolve_md_doc_theme_token — מה שהמסמך יקבל במכשיר הזה — עם השם של הערכה, ו-found: false למצביע לערכה שכבר לא קיימת. מסד שלא ענה ← 503 database_unavailable ולא ”אין ערכת מסמך“ (strict ב-_resolve_md_doc_theme_token): עד שהבחירה ידועה המודאל לא מציג כרטיסים, והתיבה בגלריה מושבתת — אחרת ”ללא“, שמוצג כברירת מחדל, היה נראה כמו המצב, ולחיצה הייתה מכבה. מאותה סיבה גם תיבת הסימון שליד הייבוא נעולה עד אז: היא שומרת בתחולה שבבורר, ועד שהשרת ענה הבורר מציג ”לכל המכשירים“ גם למי שבחר ”רק במכשיר הזה“. השמירה עצמה (saveDocTheme ב-theme-importer.js) מסרבת כשהבחירה לא ידועה, כך שאף מסלול לא שומר בתחולה שלא נקראה. מה ששני המסכים צריכים — הטוקן של ערכה מתוך /api/themes/list, הקריאה והשמירה, עם תקרת זמן לכל בקשה — כתוב פעם אחת, ב-webapp/static/js/utils/md-doc-theme.js (window.CkMdDocTheme).
איך זה בנוי
המטרה מוגדרת במדויק: כל אלמנט בכרטיס צריך להיראות בדיוק כמו כשערכת המסמך היא ערכת הממשק. משתני CSS עוברים בירושה, ולכן הבסיס פשוט — המשתנים של ערכת המסמך מוצהרים על הכרטיס (build_md_doc_theme_css, בבלוק <style id="md-doc-theme">), וכל כלל בתוך הכרטיס שקורא משתנה מקבל אותם. אבל ארבעה דברים היו נשארים מערכת הממשק, וכל אחד מטופל:
משתנה ברשימה הלבנה שערכת המסמך לא מצהירה עליו — בעיקר ווי הדריסה: הכותרות הצהובות של morass היו מגיעות למסמך של ערכה שלא מצהירה על
--md-heading-color-override.build_md_doc_theme_cssמאפס כל משתנה כזה ל-initial, כלומר ”לא מוגדר“, כמו בערכה שאינה מצהירה עליו.ברירות המחדל של הצבעים. משתנה שגם ערכת המסמך לא מצהירה עליו וגם אינו וו —
--secondary, למשל, שממנו נגזר צבע שמות הפונקציות בקוד כשלערכה איןtokenColors— מגיע בעמוד רגיל מבלוק ה-:rootשלbase.html. הבלוק הזה חל גם על הכרטיס (הבורר השני שלו), ולכן הכרטיס חוזר אליהן לפני שהמשתנים של ערכת המסמך דורסים. מה שאינו צבע —--ui-font-scaleו---scrollbar-width— בבלוק:rootנפרד, כי הוא חייב לחול רק על השורש.משתנים שנגזרים ממשתנים אחרים על
:root— הנייר (--md-paper-*ב-md-content-colors.css) וצבעי הקטעים המתקפלים והסימון (ב-markdown-enhanced.css). הם מחושבים פעם אחת על השורש ועוברים לכרטיס כצבע הסופי של ערכת הממשק. הבלוקים שלהם חלים גם על הכרטיס, ושם הם נגזרים שוב מצבעי ערכת המסמך.הדגשת התחביר. הכללים של ערכת הממשק מוזרקים לכל העמוד עם
!important. בעמוד שיש בו ערכת מסמךbase.htmlמעביר אותם דרךexclude_md_doc_theme_from_hljs_css, וכל כלל highlight.js מקבל תנאי שמוציא את הכרטיס — בלי לשנות את הספציפיות שלו, ובלי לגעת בכללים אחרים. הכללים של ערכת המסמך נכנסים לכרטיס דרךrebase_hljs_css(שנכתב לייצוא), עם הכלל הבסיסי.hljs(include_base). בכל עמוד אחר ה-CSS של ערכת הממשק יוצא כמו שהוא.
ועוד שני חלקים קטנים: רקע הכרטיס הוא הרקע של העמוד של ערכת המסמך עם שכבת הזכוכית מעליו (הכלל ב-md_preview.html), כי מאחוריו עמוד בערכה אחרת; ובחירת הבהיר או הכהה של Mermaid נעשית לפי --bg-primary של הכרטיס.
הקאש. ה-CSS של ערכת המסמך מרונדר לתוך ה-HTML, ולכן _md_doc_theme_etag_key — הטוקן וה-updated_at של הערכה — נכנס ל-ETag של /md/<id> ולמפתח הקאש שלו. בלי זה בחירה, כיבוי או עריכה של הערכה היו מחזירים 304 עם המראה הישן. המפתח נוסף רק כשיש ערכת מסמך, ולכן מי שאין לו כזו מקבל את אותו ETag כמו קודם.
מה לא עובר לערכת המסמך
הפתקים הדביקים: הם לא בתוך הכרטיס (נתלים על העמוד), ויש להם נייר משלהם בכל ערכה.
תוכן העניינים הצף: מחוץ לכרטיס.
צבעים שקבועים בכל ערכה: כותרות ה-callouts (
.admonition-*ב-markdown-enhanced.css) והרקע השקוף שלהן, הסימון==טקסט==, ה-#ליד כותרות וכפתור ”העתק כמארקדאון“. הם נראים בדיוק כמו כשערכת המסמך היא ערכת הממשק — הם פשוט לא באים מאף ערכה.בורר צבעי הרקע (”נייר חם“ ודומיו) מוצג רק בערכות מובנות בהירות, ולכן לא מופיע כשערכת המסמך פעילה.
מחוץ להיקף: מצב קריאה (עמוד נפרד), תצוגת השיתוף
/share/<id>, התצוגה החיה בעמוד העריכה ותצוגת ה-Markdown של דפדפן הריפו.
הערה
ממצא שלא תוקן כאן: ערכה ציבורית כערכת ממשק מקבלת היום דיאגרמות Mermaid כהות גם כשהיא בהירה — ההחלטה ב-md_preview.html מחשבת בהירות רק כש-data-theme הוא custom. בכרטיס של ערכת מסמך ההחלטה היא לפי הבהירות גם לערכה ציבורית. תיקון בעמוד הרגיל היה משנה את המראה של ערכות ציבוריות קיימות, ולכן הוא נשאר להחלטה נפרדת.
tests/test_md_doc_theme_browser.py מודד בדפדפן את הכרטיס מול העמוד שבו ערכת המסמך היא ערכת הממשק — כל אלמנט, כולל פסאודו-אלמנטים, ריחוף ופוקוס — בכהה עם בהירה ולהפך, בערכה בלי tokenColors ובערכה ציבורית בשני הצדדים; בודק שמחוץ לכרטיס דבר לא השתנה; ושבערכה מובנית ערכת המסמך רדומה. הוא גם מפעיל את שני המסכים דרך הממשק שלהם: את התיבה בגלריה, ואת המצב ”ערכת מסמך“ במודאל — מעבר וכיבוי שהכרטיס עוקב אחריהם, בחירה שנשארת במכשיר, ההערה בערכת ממשק מובנית, עדכון בלי טעינה מחדש בעמוד שאין בו הכרטיס, מסך בלי כרטיסים כשהבחירה הנוכחית לא נטענה, שמצב ”ערכת ממשק“ חוזר בדיוק למה שהיה, שכל עוד שמירה לא חזרה שום בחירה נוספת לא יוצאת מהמודאל, ושייבוא בגלריה לא מחיל ערכה על המסמך לפני שהבחירה הנוכחית נקראה — בשניהם הטסט מחזיק את הבקשה בדרך. tests/test_md_doc_theme.py בודק בלי דפדפן את השמירה, הבחירה הנוכחית, ה-ETag, ה-HTML, ושהבורר של השורש זהה בכל הקבצים שכותבים אותו.
הדגשת תחביר (Syntax Highlighting)
כאשר מייבאים ערכת VS Code עם tokenColors, parse_vscode_theme ממיר אותם אוטומטית ל-syntax_css עם שלוש קבוצות כללים, אחת לכל מנוע צביעה: CodeMirror בעורך (generate_codemirror_css_from_tokens), highlight.js בבלוקי הקוד של Markdown (generate_hljs_css_from_tokens), ו-Pygments (generate_pygments_css_from_tokens). מה שעובר מהן בפרסום לציבורית — הדגשת התחביר בפרסום.
ארכיטקטורה
זרימת המרת צבעים מ-VS Code ל-CodeMirror:
tokenColors (VS Code)
│
▼
VSCODE_TO_CM_TAG מיפוי
│
▼
syntax_colors JSON
│
▼
HighlightStyle.define() (CodeMirror)
מנגנון Fallback
כאשר ערכה לא מגדירה צבע לתג ספציפי, המערכת יורשת מתגים הוריים:
function(definition(variableName))
│
├── יורש מ-definition(variableName)
│ │
│ └── יורש מ-variableName
│ │
│ └── יורש מ-name
│
└── יורש מ-function(variableName)
│
└── יורש מ-variableName
דוגמה:
אם הערכה מגדירה צבע רק ל-variableName, כל ההגדרות שיורשות ממנו יקבלו את אותו הצבע עד שתוגדר דריסה ספציפית.
CodeMirror CSS Classes
מעבר ל-Tags המשמשים ב-HighlightStyle.define(), המערכת תומכת גם ב-CSS Classes עבור classHighlighter. אלו מאפשרים דריסה ישירה ב-CSS:
Classes בסיסיים:
CSS Class |
תיאור |
|---|---|
|
הערות |
|
מחרוזות (רגילות / template) |
|
מילות מפתח |
|
מספרים |
|
אופרטורים |
|
סימני פיסוק |
|
קבועים וערכי boolean |
|
ערכים ליטרליים |
משתנים ופונקציות:
CSS Class |
תיאור |
|---|---|
|
משתנים רגילים |
|
הגדרות משתנים (צבע שונה) |
|
משתנים מקומיים (לעתים עם italic) |
|
משתנים מיוחדים (self, this, super) |
|
פונקציות |
|
מאקרו / decorators |
טיפוסים ומחלקות:
CSS Class |
תיאור |
|---|---|
|
שמות מחלקות |
|
שמות טיפוסים |
|
namespaces / modules |
|
שמות properties |
|
הגדרות properties |
HTML/XML:
CSS Class |
תיאור |
|---|---|
|
תגיות HTML/XML |
|
מאפיינים |
|
סוגריים זוויתיים |
עיצוב טקסט (Markdown):
CSS Class |
תיאור |
|---|---|
|
כותרות |
|
טקסט נטוי (italic) |
|
טקסט מודגש (bold) |
|
קישורים |
|
ציטוטים |
|
קוד inline |
מיוחדים:
CSS Class |
תיאור |
|---|---|
|
מטא-דאטה |
|
labels |
|
שורות שנוספו (git diff) |
|
שורות שנמחקו (git diff) |
|
שורות ששונו |
|
קוד לא תקין |
דוגמת CSS לדריסה:
/* דריסת צבע הגדרות פונקציות */
:root[data-theme="custom"] .tok-variableName.tok-definition {
color: #7aa2f7 !important;
font-weight: bold !important;
}
/* משתנים מקומיים באיטליק */
:root[data-theme="custom"] .tok-variableName.tok-local {
color: #bb9af7 !important;
font-style: italic !important;
}
/* self/this בצבע מיוחד */
:root[data-theme="custom"] .tok-variableName2 {
color: #f7768e !important;
}
/* שורות שנוספו בדיף */
:root[data-theme="custom"] .tok-inserted {
color: #9ece6a !important;
background: rgba(158, 206, 106, 0.1);
}
/* שורות שנמחקו בדיף */
:root[data-theme="custom"] .tok-deleted {
color: #f7768e !important;
background: rgba(247, 118, 142, 0.1);
}
הערה
ה-!important נדרש כדי לדרוס את ה-inline styles שמוזרקים על ידי CodeMirror themes.
הסלקטור :root[data-theme="custom"] מבטיח שהדריסות יחולו רק כשערכה מותאמת פעילה.
אבטחה וולידציה
ולידציית צבעים
המערכת מאפשרת רק פורמטים בטוחים:
פורמטים נתמכים:
#fff Hex קצר (3 תווים)
#ffff Hex עם alpha (4 תווים)
#ffffff Hex מלא (6 תווים)
#ffffffff Hex עם alpha (8 תווים)
rgb(r, g, b) RGB (ערכים 0-255)
rgba(r, g, b, a) RGBA עם שקיפות (alpha 0-1)
ערכים חסומים (אבטחה):
url(...) CSS injection
expression(...) IE legacy injection
javascript: XSS
data: Data URI injection
@import CSS import injection
סניטציה
המערכת מבצעת מספר שלבי ניקוי:
הסרת הערות JSONC – לפני פרסור ה-JSON
בדיקת תקינות JSON – וולידציה של מבנה הקובץ
ולידציית צבעים – לפי ה-Regex המגביל
בדיקת whitelist – רק משתנים מוכרים מותרים
הגבלת גודל – מניעת קבצים גדולים מדי
אזהרה
לא כל ערך פסול מטופל באותה דרך, וההבדל חשוב:
ערך פסול בבלוק
variables— הייבוא נדחה עם400, וההודעה מציינת את המפתח.מפתח שאינו ברשימה הלבנה — עובר את הוולידציה ואז מסונן בשקט, עם אזהרה בלוג.
ערך פסול בתוך
colors— עובר את הוולידציה, והטוקן שהוא ממופה אליו נופל לערך ברירת המחדל, עם אזהרה בלוג.
כלומר שתי הצורות האחרונות אינן מפילות את הייבוא. אם ערכה נשמרה אך צבע מסוים אינו מופיע, זו הסיבה הסבירה.
API Reference
Endpoints
רשימת ערכות:
GET /api/themes
מחזיר רשימת כל הערכות של המשתמש (ללא variables הכבדים).
פרטי ערכה:
GET /api/themes/<id>
מחזיר ערכה מלאה כולל variables לעריכה.
יצירת ערכה:
POST /api/themes
Content-Type: application/json
{
"name": "My Theme",
"variables": {...}
}
ייבוא ערכה:
POST /api/themes/import
Content-Type: application/json
{
"json_content": "{...JSON content...}"
}
הפורמט מזוהה מתוך התוכן עצמו ולא נמסר כפרמטר: קובץ שיש בו מפתח colors מפורסר כערכת VS Code, וכל השאר כפורמט המקומי. לחלופין אפשר להעלות ב-multipart/form-data תחת השדה file, בסיומת .json.
עדכון ערכה:
PUT /api/themes/<id>
Content-Type: application/json
{
"name": "Updated Name",
"variables": {...}
}
הפעלת ערכה:
POST /api/themes/<id>/activate
מפעיל את הערכה (מכבה את כל האחרות) ומעדכן ui_prefs.theme="custom".
ביטול הפעלה:
POST /api/themes/deactivate
מבטל את כל הערכות המותאמות וחוזר ל-Classic.
מחיקת ערכה:
DELETE /api/themes/<id>
מוחק ערכה. אם הייתה פעילה – חוזרים ל-Classic.
מבנה תגובה
{
"success": true,
"theme": {
"id": "uuid-string",
"name": "My Theme",
"description": "תיאור הערכה",
"is_active": true,
"source": "vscode",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z",
"variables": {
"--bg-primary": "#1a1b26"
// ... additional variables
},
"syntax_css": "/* CodeMirror CSS */",
"syntax_colors": {
"keyword": {"color": "#7aa2f7"}
// ... additional colors
}
}
}
פתרון בעיות (Troubleshooting)
בעיות נפוצות
”קובץ JSON לא תקין“:
בדקו שאין הערות שגויות (
//בתוך מחרוזת)ודאו שכל הסוגריים מאוזנים
בדקו שאין פסיקים מיותרים בסוף
צבעים לא מופיעים:
ודאו שפורמט הצבע תקין (
#fff,#ffffff,rgb(...))בדקו שהמשתנה נמצא ברשימת ה-whitelist
בדקו את לוג האזהרות בקונסול
הדגשת תחביר לא עובדת:
ודאו שהערכה מיובאת מ-VS Code ומכילה
tokenColorsערכות שנוצרו ידנית לא כוללות הדגשת תחביר ייחודית
בדקו שה-
syntax_colorsנשמר כראויבערכה ציבורית: בדקו אם בפרסום הופיעה אזהרה על כללי הדגשה שלא נשמרו (הדגשת התחביר בפרסום)
הערכה לא נשמרת:
ודאו שאתם מחוברים למערכת
בדקו שלא עברתם את מגבלת 10 הערכות
בדקו הרשאות כתיבה למסד הנתונים
דוגמה לייבוא ערכת Nord
הורידו את קובץ
nord-theme.jsonמהריפו הרשמיפתחו את Theme Builder בהגדרות
לחצו ”ייבוא מ-VS Code“
העלו את הקובץ
שמרו והפעילו
קישורים קשורים
ראה גם
מערכת ערכות הנושא והטוקנים החדשה – תיעוד ארכיטקטורת הטוקנים והערכות
GUIDES/custom_themes_guide.md– מדריך פנימי מורחבservices/theme_parser_service.py– קוד המקור של הפרסורservices/theme_presets_service.py– ניהול ערכות מוכנותwebapp/static/data/theme_presets.json– קובץ ה-Presets