مبدل Markdown به Confluence

تیم مهندسی، معمار نرم‌افزار، مدیر محصول و نویسنده فنی سخت به Markdown برای پیش‌نویس مستندات فنی، رکورد تصمیم معماری (ADR)، طراحی سامانه و فایل README مخزن وابسته‌اند. Markdown سبک، خوانای انسانی، نسخه‌کنترل‌شده از راه Git و قابل حمل در محیط توسعه‌دهنده است. اما تیم سازمانی اغلب از Atlassian Confluence به‌عنوان پایگاه دانش مرکزی سازمانی و ویکی داخلی استفاده می‌کند. پر کردن فاصله میان فایل Markdown مبتنی بر Git و صفحه Confluence از نظر تاریخی برای بخش مهندسی فرایندی دردناک و تکه‌تکه بوده است.

چرا تبدیل Markdown به Confluence چالش‌برانگیز است

Confluence متن خام Markdown چسبانده‌شده در ویرایشگر وب را به‌صورت بومی رندر نمی‌کند. Confluence Cloud مدرن از قالب سند Atlassian (ADF) و قالب ذخیره زیرین Confluence (شمای XML مبتنی بر XHTML) استفاده می‌کند، در حالی که نمونه قدیمی Confluence Server و Data Center به Wiki Markup کانفلوئنس وابسته‌اند. وقتی توسعه‌دهنده Markdown استاندارد را مستقیم در ویرایشگر دیداری صفحه Confluence می‌چسباند، عنصر رایج قالب به شکل خسته‌کننده می‌شکند:

• بلوک کد برجسته‌سازی نحو را از دست می‌دهد: فنس کد سه‌بک‌تیک ساده (```python) به پاراگراف متن ساده بدون قالب یا جعبه عمومی ازپیش‌قالب‌شده برمی‌گردد و رنگ‌آمیزی نحو و تعریف زبان را حذف می‌کند.
• جدول از هم می‌پاشد: جدول Markdown حاوی جداکننده لوله (|) به‌صورت جدول ساخت‌یافته HTML کانفلوئنس رندر نمی‌شود و بازسازی دستی سرستون، ردیف و ستون در ویرایشگر دیداری لازم است.
• کال‌اوت و نقل‌قول ناهم‌تراز می‌شود: نقل‌قول قالب را از دست می‌دهد و بازساخت دستی در ویرایشگر دیداری کانفلوئنس می‌خواهد.
• سلسله‌مراتب عنوان و لنگر از همگام خارج می‌شود: ساختار عنوان (# H1، ## H2) نگاشت استاندارد فهرست مطالب را از دست می‌دهد و لنگر پیوند عمیق در مقاله فنی بلند می‌شکند.

ریسک امنیت مبدل مبتنی بر سرور شخص ثالث

بسیاری از ابزار محبوب تبدیل آنلاین Markdown متن کاربر را با درخواست HTTP POST به نقطه پایانی سرور دوردست پردازش می‌کنند. وقتی توسعه‌دهنده مستندات داخلی نرم‌افزار، نمودار زیرساخت، کلید API، شمای پایگاه یا الگوریتم اختصاصی را با مبدل میزبانی‌شده ابری تبدیل می‌کند، ناخواسته ریسک انتقال داده حساس سازمانی روی زیرساخت شخص ثالث را می‌پذیرد.

سیاست امنیت شرکتی، استاندارد انطباق SOC 2، الزام ISO 27001 و مقررات HIPAA بارگذاری مستندات کد داخلی روی سرویس وب بررسی‌نشده را سخت ممنوع می‌کند. Utiliome این آسیب‌پذیری بنیادی امنیت را با اجرای کل موتور تجزیه Markdown و ترجمه Wiki Markup کانفلوئنس محلی داخل مرورگر حل می‌کند. با بهره‌گیری از استاندارد مدرن API وب JavaScript و منطق تبدیل سمت کاربر، متن Markdown هرگز DOM مرورگر را ترک نمی‌کند. هیچ فراخوان API ارسال نمی‌شود، هیچ پایگاه دوردست پرس‌وجو را ثبت نمی‌کند و هیچ مالکیت فکری شرکتی به سرور بیرونی افشا نمی‌شود.

درک خروجی Wiki Markup کانفلوئنس

هنگام مهاجرت مستندات توسعه‌دهنده به Confluence، تبدیل به Wiki Markup کانفلوئنس نحو تمیز و قابل حمل می‌دهد که مستقیم با گفتگوی توکار Insert Markup کانفلوئنس کار می‌کند (در هر دو Confluence Cloud و Server/Data Center در دسترس):

• بلوک کد فنس‌شده: به ماکرو {code} یا {code:lang} ترجمه می‌شود در حالی که محتوای کد دست‌نخورده می‌ماند.
• عنوان و قالب متن: عنوان از # به h1. تا h6. نگاشت می‌شود، پررنگ به *bold*، ایتالیک به _italic_ و خط‌خورده به -strike-.
• جدول داده: جدول لوله‌ای Markdown به جدول بومی ویکی کانفلوئنس با سلول سرستون || و سلول بدنه | تبدیل می‌شود.
• پیوند و فهرست: پیوند به [text|url] تبدیل می‌شود و فهرست گلوله/شماره‌دار به نماد * و # کانفلوئنس تبدیل می‌گردد.

گردش کار گام‌به‌گام برای همگام‌سازی خودکار مستندات

ادغام تبدیل Markdown به Confluence در گردش کار روزانه توسعه کمتر از ۳۰ ثانیه می‌گیرد:

1. منبع Markdown را آماده کنید: مشخصات فنی، یادداشت انتشار یا پسامرتگ اسپرینت را در VS Code، Obsidian، GitHub یا هر ویرایشگر متن پیش‌نویس کنید.
2. مبدل رایگان Utiliome را باز کنید: به صفحه مبدل در هر مرورگر مدرن وب (Chrome، Firefox، Safari، Edge) بروید.
3. فایل را بچسبانید یا رها کنید: متن را در ویرایشگر درج کنید. نشانه‌گذاری ویکی تبدیل‌شده در لحظه همزمان با تایپ یا چسباندن به‌روز می‌شود.
4. خروجی را کپی یا دانلود کنید: دکمه «کپی» را بزنید یا confluence.txt را دانلود کنید.
5. در Confluence بچسبانید: صفحه هدف Confluence را در حالت ویرایش باز کنید، Insert > Markup را انتخاب کنید (یا Ctrl+Shift+D / Cmd+Shift+D را بزنید)، Confluence Wiki را انتخاب کنید، نشانه‌گذاری را بچسبانید و Insert را بزنید تا مستندات را منتشر کنید.

برای برگه تقلب نحو و گردش کار pandoc، ببینید برگه تقلب Wiki Markup Markdown به Confluence.

برای تحویل مستندات تمیز آماده Confluence، Utiliome تبدیل نحو خط‌محور و امن برای کد انجام می‌دهد. در ادامه شکست فنی نحوه تبدیل عنصر خاص نحو Markdown به اولیه Wiki Markup کانفلوئنس آمده است:

۱. فنس کد و برجسته‌سازی نحو

در Markdown استاندارد، فنس کد با بک‌تیک سه‌گانه و مشخص‌کننده اختیاری زبان تعریف می‌شود:

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

وقتی Utiliome این بلوک را پردازش می‌کند، به ماکرو کد کانفلوئنس تبدیل می‌شود:

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

این تضمین می‌کند وقتی در Confluence درج شود، کد برجسته‌سازی کامل نحو و ساختار را نگه دارد در حالی که نویسه داخلی کد دست‌نخورده بماند.

۲. نقل‌قول

نقل‌قول 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.

۳. جدول داده ساخت‌یافته

Utiliome جدول لوله‌ای را به جدول تمیز ویکی کانفلوئنس با جداکننده ردیف سرستون || و جداکننده ردیف بدنه | تجزیه می‌کند:

خروجی Wiki Markup تبدیل‌شده:

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

۴. فهرست و قالب درون‌خطی

آیتم فهرست نامرتب (-، *، +) به خط گلوله‌ای کانفلوئنس (*، ) تبدیل می‌شود، در حالی که فهرست مرتب (1.، 1)) به نماد شماره‌دار (#، ##) نگاشت می‌شود. قالب درون‌خطی مثل bold**، *italic*، ~~strikethrough~~ و `inline code` مستقیم به معادل ویکی کانفلوئنس (*bold*، _italic_، -strikethrough- و {{inline code}}) نگاشت می‌شود.

بهترین روش برای نگهداری مستندات فنی در Git و Confluence

برای حفظ منبع واحد حقیقت در مخزن Git و فضای تیم Confluence، سازمان برتر مهندسی این روش ساده را دنبال می‌کنند:

• فایل منبع را در Git نگه دارید: همه مستندات معماری سامانه را به‌صورت فایل .md داخل مخزن اپ کنار کد ذخیره کنید.
• از Utiliome برای تبدیل استفاده کنید: هنگام نشر یادداشت انتشار عمده یا مشخصات فنی برای ذی‌نفع، Markdown را از مبدل خصوصی Utiliome عبور دهید.
• از ویرایش دستی در Confluence پرهیز کنید: Confluence را مقصد فقط‌نمایش منتشرشده برای مستندات مدیریت‌شده Git بگیرید تا رانش پیکربندی میان کد و مستندات پیشگیری شود.
• استاندارد نحو را یکدست کنید: به عنصر استاندارد GFM مثل عنوان، جدول لوله‌ای و فنس کد اتکا کنید تا تبدیل خودکار هر بار روان باشد.

تیم توسعه‌دهنده اغلب مستندات را با Markdown داخل مخزن Git پیش‌نویس می‌کند قبل از نشر به فضای سراسری شرکت Atlassian Confluence. Utiliome فنس کد Markdown را خودکار به ماکرو بلوک کد کانفلوئنس ترجمه می‌کند و جدول لوله‌ای را به نشانه‌گذاری بومی جدول کانفلوئنس تبدیل می‌کند.

مشخصات فنی مبدل نحو کانفلوئنس سمت کاربر در ادامه آمده است:

مبدل‌های همراه نحو فضای کاری را ببینید: Markdown به Jira • Markdown به Notion • Markdown به Slack • ویرایشگر Markdown.