ייצוא HTML מעוצב מעמוד הקובץ
בעמוד של קובץ Markdown (/file/<file_id>), למשתמש פרימיום או לאדמין, ”HTML מעוצב“ פותח את חלון הייצוא: ערכות מוכנות, הערכות של המשתמש, וייבוא של ערכת VS Code לייצוא אחד. ”תצוגה מקדימה“ פותחת את הקובץ בטאב חדש, ”הורד HTML“ מוריד אותו, ו“העתק קישור“ יוצר קישור שיתוף. החלון הוא webapp/templates/export/export_modal.html, והלוגיקה שלו ב-webapp/static/js/export-modal.js.
”תצוגה מקדימה“ ו“הורד HTML“ בונים את הקובץ בדפדפן, באותו מנוע כמו התצוגה החיה וכמו הייצוא מהעורך הציבורי (העורך הציבורי), ולכן מה שנראה בתצוגה החיה הוא מה שיוצא: התראות, מארקר, צ’קליסט, נוסחאות ותרשימים. קודם השרת המיר את הקובץ ב-Python-Markdown, שאינו מכיר חלק מהתחביר הזה, והקובץ שיצא היה שונה מהתצוגה.
הזרימה
הזרימה זהה לזו של העורך הציבורי, והחלקים המשותפים לשניהם ב-webapp/static/js/utils/styled-export-core.js (window.StyledExportCore):
ב“תצוגה מקדימה“ הטאב נפתח מיד, בתוך הלחיצה (
openPreviewTab), מאותה סיבה כמו בעורך: דפדפן מתיר לפתוח חלון רק זמן קצר אחרי פעולה של המשתמש.המנוע נטען, אם עוד לא נטען (
loadEngine, בסעיף המנוע נטען רק בלחיצה).הטקסט נקרא (בסעיף מאיפה מגיע הטקסט), ו-
MarkdownLiveRenderer.renderForExportמרנדר אותו לתוך אלמנט שאינו בעמוד, עם ערכת ה-Mermaid של הערכה שנבחרה.רק עכשיו ידוע אם יש במסמך נוסחה, ולכן השלד מתבקש אחרי הרינדור — עם
math=1כשיש, כדי לקבל את ה-CSS של KaTeX.המסמך נכנס לשלד במקום ההערה (
assemble), והקובץ מוצג בטאב או יורד (deliver). אחרי הורדה החלון נסגר.
הכפתורים מושבתים בזמן הבנייה, ולכל המתנה יש תקרת זמן משלה — לטעינת המנוע, לבקשת הטקסט ולבקשת השלד — כדי שבקשה שלא חוזרת לא תשאיר אותם מושבתים. כשל מוצג בחלון (describeError), והטאב שנפתח נסגר.
השלד
export_styled_skeleton ב-webapp/app.py: GET או POST ל-/export/styled/<file_id>/skeleton. השלד הוא העמוד המעוצב של הערכה, עם הערת HTML במקום התוכן (EDITOR_EXPORT_CONTENT_MARKER ב-services/styled_export_service.py), באנר עם שם הקובץ, וכיתוב בתחתית (STYLED_EXPORT_FOOTER). הוא נבנה ב-render_styled_export_skeleton.
הרשאות כמו בייצוא שבשרת. אין בשלד את תוכן הקובץ, רק את שם הקובץ ואת העיצוב, ובכל זאת הוא תחת אותם תנאים: התחברות, פרימיום או אדמין, וקובץ Markdown של המשתמש. קובץ שאינו Markdown מקבל 400.
הערכה נקבעת כמו בייצוא שבשרת, באותה פונקציה (
_styled_export_theme_from_request): ב-GETלפיtheme, כולל ערכות המשתמש מהמסד; ב-POSTערכת VS Code מ-vscode_jsonשבטופס.mathהוא1או חסר. כל ערך אחר מקבל 404.Cache-Control: no-store, כי בשלד שם הקובץ וערכות המשתמש. ה-CSP של הנתיב הוא זה של שלד העורך (_MARKDOWN_EDITOR_SKELETON_CSP).X-Export-Filename— שם הקובץ שיורד (styled_export_filename), מקודד ב-URL: כותרת HTTP היא latin-1, ושם הקובץ יכול להיות בעברית. הכותרת (styled_export_title) ושם הקובץ נגזרים כמו בייצוא שבשרת, מאותן פונקציות.
מאיפה מגיע הטקסט
מהעמוד עצמו: #rawCode, שעמוד הקובץ כבר מחזיק בשביל ”העתק“ והתצוגה המתקדמת. בקובץ שגדול מ-MAX_DISPLAY_SIZE (ב-view_file) העמוד לא מציג את הטקסט ואין בו #rawCode, ואז הטקסט מגיע מ-/download/<file_id>. שתי הדרכים מחזירות בדיוק את הגרסה שבעמוד: /download מוצא את הקובץ לפי המזהה, באותה פונקציה של עמוד הקובץ (_get_user_any_file_by_id). /api/file/<file_id>/content לא מתאים כאן, כי הוא מחזיר את הגרסה האחרונה של הקובץ (_latest_file_doc_by_id), גם כשמייצאים גרסה ישנה.
המנוע נטען רק בלחיצה
עמוד הקובץ לא טוען את התצוגה החיה, והבאנדל שלה כבד. לכן הסקריפטים שלה יושבים בעמוד בתוך <template id="styledExportEngine">, שכולל את _live_preview_scripts.html — אותה רשימה של עמודי העורך, בלי עותק שני. בתוך <template> הסקריפטים אינם נטענים ואינם רצים. בייצוא הראשון loadEngine בונה אותם מחדש כסקריפטים חיים, אחד אחרי השני, לפי הסדר.
ההבטחה היא השומר. לחיצה שנייה בזמן הטעינה מקבלת את אותה הבטחה, וכשל מאפס אותה, כדי שהלחיצה הבאה תנסה שוב.
רשומה לכל סקריפט. ניסיון חוזר משתמש בסקריפט שכבר נטען, בלי להריץ אותו שוב, ובונה מחדש רק את מה שנכשל.
תקרת זמן אחת לטעינה כולה, ולא לכל סקריפט. כשהיא נגמרת, סקריפט שעוד לא נטען — בקשה תקועה, חיבור שנפל באמצע — ננטש (
abandonPending), והניסיון הבא מבקש אותו בכתובת אחרת (retry=N): Chromium מצמיד אלמנט חדש לבקשה שעוד פתוחה לאותה כתובת, ובלי זה כל ניסיון היה מחכה לאותה בקשה תקועה עד רענון העמוד. מאותה סיבה הסקריפטים נוספים כ-async, ולאasync = false, שהיה מעמיד כל סקריפט בתור מאחורי זה שננטש; הסדר נשמר בכל מקרה, כי כל סקריפט נוסף רק אחרי שהקודם נטען. אי אפשר לבטל בקשה של אלמנט סקריפט, ולכן כשהבקשה הישנה מסתיימת בכל זאת, הסקריפט רץ פעם נוספת.test_a_hung_engine_script_is_requested_againמראה את שלושת הדברים: הבקשה החדשה, הריצה הנוספת, וייצוא שעובד אחריה.
tests/sticky-notes-target.test.js בודק שהתוכן של #styledExportEngine הוא ה-partial בלבד, ושה-partial אינו נכלל בעמוד גם מחוץ ל-<template>.
ערכת ה-Mermaid וצבעי התחביר
התרשימים מצוירים לפני שהשלד מגיע, ולכן ערכת ה-Mermaid מגיעה לדפדפן עם רשימת הערכות: mermaid_theme ב-/api/export/themes, לכל ערכה מוכנה ולכל ערכת משתמש, וב-/api/export/parse-vscode לערכת VS Code. ההכרעה ב-export_mermaid_theme: לפי category של הערכה, ולערכת משתמש, שאין לה קטגוריה שמורה, לפי הבהירות של --bg-primary — באותה נוסחה ובאותו סף כמו pageMermaidTheme ב-live-preview.js. העורך הציבורי מכריע באותה פונקציה.
צבעי התחביר בקובץ הם של highlight.js, כמו בתצוגה. לערכות הייצוא של העורך יש כללים משלהן (hljs_css). ערכה מיובאת מ-VS Code שומרת כללים תחת הקידומת של האתר, והם עוברים לקידומת של הייצוא (rebase_hljs_css). לכל ערכה אחרת — הפלטה שנגזרת מהמשתנים, כמו בתצוגה (מערכת ערכות הנושא והטוקנים החדשה).
המתג
STYLED_EXPORT_BROWSER_RENDER (ברירת מחדל true, משתני סביבה - רפרנס). ב-false ”תצוגה מקדימה“ ו“הורד HTML“ חוזרים לייצוא שבשרת, /export/styled/<file_id>, שנשאר כמו שהוא. זו דרך חזרה בלי דיפלוי של קוד.
הערך מגיע לחלון דרך
inject_globals, כ-data-browser-render, יחד עם טקסט ההערה של השלד (data-content-marker).הוא נכנס ל-ETag של עמוד הקובץ. בלעדיו, עמוד שמור היה מקבל 304 אחרי היפוך המתג, וממשיך במסלול הקודם.
export-modal.jsחדש מול עמוד ישן, בלי המאפיינים, עובד במסלול של השרת.כש-
styled-export-core.jsלא נטען (בקשה שנכשלה), ”תצוגה מקדימה“ ו“הורד HTML“ מציגים הודעה שרכיב הייצוא לא נטען, ואינם עוברים בשקט לייצוא שבשרת: זה מנוע אחר, עם תוצאה אחרת, והדרך המוצהרת אליו היא המתג. גם בעורך הציבורי הכפתורים אומרים את זה, במקום לא לעשות כלום.
הבדיקות
tests/test_styled_export_view_file.py— השלד (הרשאות, הערכה לפי הבקשה,math, הכותרות), עמוד הקובץ (המאפיינים של החלון, המנוע ב-<template>, המתג וה-ETag, קובץ שגדול מ-MAX_DISPLAY_SIZE), וההכרעות המשותפות.tests/test_styled_export_browser.py— בדפדפן: הקובץ שירד בכל סוג של ערכה, כשהוא נפתח לבד ובלי רשת; המנוע נטען רק בייצוא הראשון; תצוגה מקדימה; קובץ שגדול מ-MAX_DISPLAY_SIZE; ערכת VS Code; ייצוא שנכשל; והמתג. וקישור השיתוף: הוא נבנה אצל מי שפותח, בלי התחברות ובלי הפרת CSP; הזרקות לא רצות; עוגן בכתובת; ביטול מהלשונית; קישור מהצורה הראשונה; וקובץ גדול מדי.tests/test_styled_share_v2.py— קישור השיתוף בשרת: מה נשמר, התקרה בבתים, המתג, גוף בקשה שגוי, העמוד והמדיניות שלו, שתי הצורות, הרשימה והביטול.tests/test_styled_export_skeleton.py— צבעי highlight.js לכל סוג של ערכה, והשלד.המדידה של הקובץ שירד משותפת לייצוא מהעורך (
tests/_styled_export_harness.py).