ייצוא 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):

  1. ב“תצוגה מקדימה“ הטאב נפתח מיד, בתוך הלחיצה (openPreviewTab), מאותה סיבה כמו בעורך: דפדפן מתיר לפתוח חלון רק זמן קצר אחרי פעולה של המשתמש.

  2. המנוע נטען, אם עוד לא נטען (loadEngine, בסעיף המנוע נטען רק בלחיצה).

  3. הטקסט נקרא (בסעיף מאיפה מגיע הטקסט), ו-MarkdownLiveRenderer.renderForExport מרנדר אותו לתוך אלמנט שאינו בעמוד, עם ערכת ה-Mermaid של הערכה שנבחרה.

  4. רק עכשיו ידוע אם יש במסמך נוסחה, ולכן השלד מתבקש אחרי הרינדור — עם math=1 כשיש, כדי לקבל את ה-CSS של KaTeX.

  5. המסמך נכנס לשלד במקום ההערה (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“ מציגים הודעה שרכיב הייצוא לא נטען, ואינם עוברים בשקט לייצוא שבשרת: זה מנוע אחר, עם תוצאה אחרת, והדרך המוצהרת אליו היא המתג. גם בעורך הציבורי הכפתורים אומרים את זה, במקום לא לעשות כלום.

קישור השיתוף

”העתק קישור“ יוצר קישור (api_create_styled_share, POST /api/export/styled/<file_id>/share) שנפתח בלי התחברות, ב-/shared/styled/<token> (public_shared_styled). האוסף, הצורות של המסמך והאינדקסים מוגדרים ב-styled_shares.py. לאוסף יש כותב נוסף: ”צור קישור“ בעורך הציבורי, של גולש שאינו מחובר, שנשמר עם origin משלו ומוגש באותו ראוט עם כמה הבדלים (הקישור הציבורי (”צור קישור“)). את השדות של הצורה השנייה בונים שני הכותבים באותה פונקציה, markdown_share_fields.

  • מה נשמר. הטקסט של הגרסה ששותפה, כמו שהוא (markdown), והערכה כמו ש-get_export_theme החזיר אותה ברגע השיתוף (theme), עם format = STYLED_SHARE_FORMAT_MARKDOWN. שינוי מאוחר בערכה של המשתמש לא משנה קישור שכבר נשלח. ערכת ה-Mermaid נגזרת מהערכה בכל צפייה, ולא נשמרת לידה.

  • איך הוא נבנה. העמוד הוא השלד של הייצוא של המחוברים (render_styled_share_page), עם הטקסט כ-JSON (tojson, ולכן </script> בטקסט אינו סוגר את התגית), עם המנוע של התצוגה החיה מאותו _live_preview_scripts.html, ועם webapp/static/js/styled-share-view.js, שמרנדר את הטקסט בדפדפן של מי שפותח ומכניס אותו במקום ההערה. ה-CSS של KaTeX נכנס רק כשיש בטקסט $, כי כל נוסחה מתחילה בו (md-math-plugin.js). עד שהרינדור נגמר מוצגת שורת ”טוען“, ואם הוא נכשל — הודעה במקומה.

  • כפתורי ההעתקה מתווספים אחרי שהמסמך נכנס לעמוד: COPY_CODE_SCRIPT רץ כשהעמוד נטען ומשאיר את window.ckAttachCopyButtons, ש-styled-share-view.js קורא לה. היא לא מוסיפה כפתור שני לבלוק שכבר יש לו. השינוי הזה בסקריפט שינה את ה-hash שלו, וה-hash הקודם נשמר ב-PREVIOUS_COPY_CODE_SCRIPT_CSP_HASHES, כי קישורים מהצורה הראשונה שומרים את הסקריפט של אז.

  • CSP (styled_share_page_csp): Markdown של בעל הקובץ מרונדר בדפדפן של מי שפותח, בדומיין שלנו. ההגנה הראשונה היא המנוע (markdown-it עם html: false, ‏Mermaid ב-strict), והמדיניות היא השכבה השנייה: default-src 'none', ‏``script-src »self«`` עם ה-hash של סקריפט ההעתקה ובלי שום סקריפט inline אחר, form-action, frame-ancestors ו-base-uri חסומים. ה-docstring של הפונקציה אומר איפה נכתב ההיתר כשפיצ’ר יצטרך משהו מהם. tests/test_styled_export_browser.py פותח קישור בדפדפן, בלי התחברות, ובודק שאין אף הפרה, ושמה שהוזרק לעמוד לא רץ.

  • תקרת גודל. טקסט מעל STYLED_SHARE_MAX_MARKDOWN_BYTES נדחה ב-413 (file_too_large_to_share), ולא נחתך: הרינדור קורה בדפדפן של מי שפותח, והעמוד קופא בזמן הרינדור. המדידה שהתקרה נשענת עליה — בהערה שמעל הקבוע.

  • מטמון. העמוד מוגש עם no-cache, ולא עם max-age: קישור שבוטל או שפג מפסיק להיפתח מיד, ולא מעותק שמור.

  • קישורים מהצורה הראשונה — styled_html, העמוד שהשרת בנה ב-Python-Markdown ברגע השיתוף — מוגשים כמו שנשמרו, עם styled_share_csp. מסמך שאינו אף אחת מהצורות מקבל 404.

  • המתג. כש-STYLED_EXPORT_BROWSER_RENDER כבוי, גם קישור חדש נוצר בצורה הראשונה, כמו קודם (בלי תקרת הגודל). קישור שכבר נוצר בצורה השנייה ממשיך להיבנות בדפדפן: בנייה בשרת בכל צפייה הייתה עבודה כבדה בכתובת ציבורית.

הרשימה והביטול

הלשונית ”קישורים“ בחלון הייצוא מציגה את הקישורים שהמשתמש יצר לקובץ (api_list_styled_shares, GET /api/export/styled/<file_id>/shares), מהחדש לישן, ומכל אחד אפשר להעתיק או לבטל.

  • לפי הישות, ולא לפי הגרסה. הרשימה היא של הקישורים לאותו שם קובץ, גם אלה שנוצרו מגרסה אחרת שלו; file_id רק מאתר את השם. קישור מהעורך הציבורי לא מופיע בה: אין לו user_id ואין לו שם קובץ. היא מציגה עד STYLED_SHARES_LIST_LIMIT הקישורים החדשים, וקישור שפג ועוד לא נמחק נספר במגבלה ואינו מוצג. השאילתה מחזירה רק את השדות שמוצגים — בלי הטקסט, ה-HTML והערכה — ונשענת על האינדקס styled_shares_by_file. קישור שפג ועוד לא נמחק לא מוצג.

  • הביטול (api_revoke_styled_share, POST /api/export/styled/shares/<token>/revoke) מוחק את המסמך, רק כשהוא של המשתמש, ובודק שבאמת נמחק מסמך (deleted_count). POST ולא GET, כי זו פעולה בלתי הפיכה, ורק עם Content-Type של JSON (אחרת 415): הקישור ציבורי, וטופס מאתר אחר היה יכול לבטל אותו בשם בעליו המחובר.

  • בלי דרישת פרימיום. מי שכבר אינו פרימיום עדיין רואה ומבטל קישורים שיצר.

  • אדמין מוחק כל קישור מעוצב, גם של משתמש מחובר, מ-/admin/styled-shares (הקישור הציבורי (”צור קישור“)).

הבדיקות

  • 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).