ממיר Markdown ל-Confluence

צוותי פיתוח, ארכיטקטים, מנהלי מוצר וכותבים טכניים כותבים תיעוד, רשומות החלטת ארכיטקטורה (ADR), עיצובי מערכת וקבצי README ב-Markdown. Markdown קל, קריא, נשמר ב-Git ונייד בין סביבות. בארגונים רבים בסיס הידע הוא Atlassian Confluence. הגשר בין קובצי Markdown ב-Git לעמודי Confluence היה עד עכשיו תהליך שבור.

למה ההמרה ל-Confluence קשה

Confluence לא מרנדר Markdown גולמי שמדביקים בעורך. Confluence Cloud משתמש ב-Atlassian Document Format (ADF) וב-Confluence Storage Format (סכמת XML מבוססת XHTML), ומופעי Server ו-Data Center ישנים נשענים על סימון ויקי. כשמדביקים Markdown לעורך החזותי, העיצוב נשבר:

• בלוקי קוד מאבדים הדגשת תחביר: גדרות משולשות (```python) הופכות לפסקה או לתיבה גולמית, בלי צבע שפה.
• טבלאות מתפרקות: טבלאות עם מפרידי | לא הופכות לטבלאות HTML של Confluence, וצריך לבנות כותרות ושורות ידנית.
• ציטוטים זזים: ציטוטים מאבדים עיצוב ודורשים בנייה מחדש.
• היררכיית כותרות ועוגנים: מבני # H1 ו-## H2 מאבדים מיפוי לתוכן עניינים ושוברים עוגנים במאמרים ארוכים.

סיכון האבטחה של ממירים בשרת

כלים אונליין רבים שולחים את הטקסט ב-HTTP POST לשרת מרוחק. כשממירים תיעוד פנימי, תרשימי תשתית, מפתחות API, סכמות מסד או אלגוריתמים קנייניים בממיר בענן, הנתונים עוברים בתשתית של צד שלישי.

מדיניות אבטחה, SOC 2, ISO 27001 ו-HIPAA אוסרים להעלות תיעוד קוד פנימי לשירות לא מאומת. Utiliome מריצה את כל פיענוח ה-Markdown ואת תרגום סימון הוויקי בדפדפן. הטקסט לא עוזב את ה-DOM. אין קריאות API, אין מסד שרושם שאילתות, ואין חשיפה של קניין רוחני.

מהו פלט סימון הוויקי של Confluence

בהעברת תיעוד מפתחים, סימון ויקי מתחבר לתיבת Insert Markup המובנית (ב-Cloud וב-Server/Data Center):

• בלוקי קוד מגודרים: הופכים למאקרו {code} או {code:lang}, והקוד עצמו לא משתנה.
• כותרות ועיצוב: # עד h1. ועד h6., מודגש ל-*bold*, נטוי ל-_italic_, קו חוצה ל--strike-.
• טבלאות: טבלאות צינור הופכות לטבלאות ויקי עם תאי כותרת || ותאי גוף |.
• קישורים ורשימות: קישורים ל-[text|url], רשימות תבליט ומספור לסימון * ו-#.

תהליך עבודה לסנכרון תיעוד

שילוב ההמרה בשגרה לוקח פחות מ-30 שניות:

1. הכינו את מקור ה-Markdown: כתבו מפרט, הערות גרסה או סיכום ספרינט ב-VS Code, ב-Obsidian, ב-GitHub או בכל עורך.
2. פתחו את הממיר החינמי של Utiliome: בכל דפדפן מודרני (Chrome, Firefox, Safari, Edge).
3. הדביקו או גררו קובץ: הטקסט נכנס לעורך, וסימון הוויקי מתעדכן בזמן אמת.
4. העתיקו או הורידו: לחצו על 'העתקה' או הורידו confluence.txt.
5. הדביקו ב-Confluence: פתחו את העמוד לעריכה, בחרו Insert > Markup (או Ctrl+Shift+D / Cmd+Shift+D), בחרו Confluence Wiki, הדביקו ולחצו Insert.

לגיליון תחביר ולתהליך pandoc: גיליון המרה מ-Markdown לסימון ויקי של Confluence.

כדי להפיק תיעוד נקי ל-Confluence, Utiliome ממירה תחביר שורה-שורה בלי לגעת בתוכן הקוד. כך רכיבים ספציפיים הופכים לסימון ויקי:

1. גדרות קוד והדגשת תחביר

ב-Markdown גדר קוד היא שלושה גרשיים אחוריים ושפת תכנות אופציונלית:

```typescript
interface UserProfile {
  id: string;
  email: string;
  role: 'admin' | 'user';
}
```

Utiliome הופכת את הבלוק למאקרו קוד של Confluence:

{code:typescript}
interface UserProfile {
  id: string;
  email: string;
  role: 'admin' | 'user';
}
{code}

כך הקוד שומר הדגשת תחביר ומבנה, והתווים הפנימיים לא משתנים.

2. ציטוטים

ציטוט Markdown (> quote) הופך שורה-שורה לתחביר bq. quote:

> Production database maintenance will occur on Sunday at 02:00 UTC.

מומר אוטומטית ל:

bq. Production database maintenance will occur on Sunday at 02:00 UTC.

3. טבלאות נתונים

Utiliome מפרקת טבלאות צינור לטבלאות ויקי עם || בשורת הכותרת ו-| בשורות הגוף:

פלט סימון ויקי:

||Service Name||Port||Health Check Endpoint||Status||
|Auth Service|8080|/healthz|Active|
|Payment Gateway|8081|/status|Active|

4. רשימות ועיצוב מוטמע

פריטי רשימה לא ממוינת (-, *, +) הופכים לשורות תבליט (*, ), ורשימות ממוספרות (1., 1)) לסימון (#, ##). עיצוב מוטמע כמו bold**, *italic*, ~~strikethrough~~ ו-`inline code` ממופה ל-*bold*, _italic_, -strikethrough- ו-{{inline code}}.

שיטות עבודה לתיעוד בין Git ל-Confluence

כדי לשמור מקור אמת אחד בין מאגר Git למרחבי Confluence:

• שמרו את המקור ב-Git: כל מסמכי הארכיטקטורה כקבצי .md ליד הקוד.
• המירו ב-Utiliome: כשמפרסמים הערות גרסה או מפרט לבעלי עניין, העבירו את ה-Markdown בממיר הפרטי.
• הימנעו מעריכה ידנית ב-Confluence: התייחסו ל-Confluence כיעד תצוגה לתיעוד שמנוהל ב-Git, כדי שלא ייפתח פער בין קוד לתיעוד.
• תקננו תחביר: הישענו על GFM — כותרות, טבלאות צינור וגדרות קוד — כדי שההמרה תעבור חלק.

צוותי פיתוח כותבים תיעוד ב-Markdown במאגרי Git לפני פרסום במרחבי Atlassian Confluence. Utiliome מתרגמת גדרות קוד למאקרו של Confluence וטבלאות צינור לסימון טבלה מקורי.

להלן המפרט הטכני של ממיר התחביר המקומי ל-Confluence:

ממירי תחביר נוספים: Markdown ל-Jira • Markdown ל-Notion • Markdown ל-Slack • עורך Markdown.