Ravi Markdown — راوی

خواندن مستندات Markdown فارسی، در کنار کد داخل VS Code.

نسخهٔ آزمایشی ۰٫۳٫۱: پیش‌نمایش راست‌به‌چپ و ویرایشگر اختصاصی مبتنی بر نمای کد نرم‌افزار راوی. دکمهٔ بالای ویرایشگر با نشان رنگی راوی مشخص است. ظاهر از تم VS Code پیروی می‌کند و تغییرات فایل بدون ذخیره‌کردن هم در پیش‌نمایش دیده می‌شود.

نصب آزمایشی

1. در بخش Extensions منوی … را باز کنید و Install from VSIX… را بزنید.
2. فایل ravi-markdown-0.3.1.vsix را انتخاب کنید. اگر نسخهٔ آزمایشی با ناشر ravi-local نصب است، آن را حذف کنید؛ شناسهٔ رسمی poorsmile.ravi-markdown است و VS Code این دو را افزونه‌های جدا می‌شناسد.
3. یک فایل .md باز کنید؛ دکمهٔ پیش‌نمایش در بالای ویرایشگر یا فرمان Ravi: Open Preview را بزنید.
4. میان‌بر Windows/Linux برابر Ctrl+Alt+R و macOS برابر Cmd+Alt+R است.

نمونهٔ کامل در examples/راهنمای-راوی.md قرار دارد. روی فایل Markdown در Explorer هم می‌توانید کلیک راست کنید و فرمان راوی را اجرا کنید.

ویرایش در نمای کد راوی

در پیش‌نمایش روی ویرایش متن بزنید؛ ویرایشگر اختصاصی راوی در همان گروه تب باز می‌شود. دوبار کلیک روی یک بخش از پیش‌نمایش هم آن بخش را برای ویرایش باز می‌کند. برای بازگشت، پیش‌نمایش را بزنید. محل خط جاری بین دو نما منتقل می‌شود. فرمان Ravi: Open Editor و گزینهٔ Open With → راوی — نمای کد نیز در دسترس‌اند.

نمای ویرایش از Monaco Editor 0.55.1 استفاده می‌کند: فونت Tahoma با اندازهٔ ۱۴ و فاصلهٔ خطوط ۲۵ پیکسل، شمارهٔ خطوط، رنگ‌بندی Markdown و مکان‌نما و انتخاب متن بومی Monaco. خطوط دارای حروف فارسی به‌طور خودکار راست‌چین می‌شوند؛ بلوک‌های کد چپ‌چین می‌مانند. ابزارهای اصلی پایین ویرایشگر هستند و ابزارهای تکمیلی در منوی «بیشتر» قرار دارند تا در پنل باریک هم قابل استفاده باشند.

• آیکن‌ها از Google Material Symbols هستند و به‌صورت محلی همراه افزونه ارائه می‌شوند.
• نوار ابزار: جدول، پررنگ، مورب، پیوند، کد درون‌خطی، تیتر، فهرست، جست‌وجو، اصلاح فارسی، نیم‌فاصله و Undo/Redo.
• اصلاح فارسی روی متن انتخاب‌شده یا خط جاری اعمال می‌شود: ی/ک فارسی و فاصله‌گذاری اطراف «،؛؟». بلوک و کد درون‌خطی، URL، مقصد لینک، HTML و شناسه‌های ترکیبی محافظت می‌شوند. این ابزار غلط‌گیر املایی یا بازنویس هوشمند نیست.
• پیشنهادها در حاشیه مشخص‌اند؛ Ctrl+. / Cmd+. پنل پیشنهادها را باز می‌کند تا هر اصلاح را جدا اعمال کنید.
• Shift+Space نیم‌فاصله درج می‌کند. تنظیم raviMarkdown.halfSpaceKey گزینه‌های Mod-Shift-Space و Alt-Space را هم دارد؛ Mod یعنی Ctrl در Windows/Linux و Cmd در macOS.
• Ctrl/Cmd+S ذخیره، Ctrl/Cmd+Z واگرد، Ctrl/Cmd+Shift+Z ازنو، Ctrl/Cmd+F جست‌وجو و Ctrl/Cmd+B/I قالب‌بندی است.
• شکست خطوط و اندازهٔ متن از پایین ویرایشگر تنظیم می‌شوند.

متن به سند اصلی VS Code وصل است؛ تغییر در ویرایشگر معمولی هم به راوی منتقل می‌شود. اگر تغییر بیرونی با تایپ شما هم‌زمان شود، افزونه هر دو نسخه را نگه می‌دارد: ابتدا «باز کردن نسخهٔ من» یک سند جدا و ذخیره‌نشده می‌سازد؛ سپس «بارگیری نسخهٔ فایل» فعال می‌شود. نسخهٔ جدا را در صورت نیاز ذخیره کنید. پیش‌نویس‌های تأییدنشده برای بازیابی در storage محلی workspace نگه‌داری می‌شوند و پس از همگام‌سازی پاک می‌شوند.

رفتار و محدودیت‌ها

• هر پیش‌نمایش به همان فایل متصل می‌ماند؛ بازکردن فایل دوم، محتوای فایل اول را جابه‌جا نمی‌کند.
• پیش‌نمایش فقط می‌خواند؛ تغییرهای نمای ویرایش به همان سند Markdown اعمال می‌شوند. افزونه حساب کاربری و telemetry ندارد و برای رندر یا ویرایش به سرور وصل نمی‌شود.
• تصویرهای نسبی داخل پوشهٔ مجاز پروژه نمایش داده می‌شوند. تصاویر اینترنتی بارگیری نمی‌شوند؛ لینک‌های وب تنها با کلیک باز می‌شوند.
• HTML خام به‌صورت متن نمایش داده می‌شود. Mermaid، فرمول ریاضی، PDF و اتصال به حساب راوی در نسخهٔ اول پیاده‌سازی نشده‌اند.
• لینک به فایل محلی، فایل را در ویرایشگر باز می‌کند؛ جابه‌جایی به تیتر در همان سند پشتیبانی می‌شود. ارجاع به تیتر در فایل دیگر هنوز پشتیبانی نمی‌شود.
• اندازهٔ پیش‌فرض از تنظیم raviMarkdown.fontSize قابل تغییر است؛ انتخاب دکمه‌های A+/A− برای همان پنل اولویت دارد.
• این نسخه برای VS Code دسکتاپ است؛ بستهٔ Web Extension برای vscode.dev ارائه نشده است.

توسعه و ساخت

Node.js 22 یا جدیدتر پیشنهاد می‌شود. از همین پوشه اجرا کنید:

npm ci
npm run check
npm run build
npm test
npm run test:ui
npm run test:editor
npm run test:host
npm run package

آزمون رابط به Chromium در Playwright نیاز دارد (npx playwright install chromium). آزمون میزبان به‌صورت پیش‌فرض VS Code آزمایشی را دریافت می‌کند؛ با متغیر VSCODE_EXECUTABLE_PATH می‌توان مسیر executable نصب‌شده را تعیین کرد. پروفایل آزمایشی از پروفایل شخصی جداست.

برای اجرای آزمون رابط با Chrome نصب‌شده، متغیر PLAYWRIGHT_CHANNEL=chrome را تعیین کنید.

برای اشکال‌زدایی پوشهٔ افزونه را در VS Code باز کنید و F5 بزنید (ابتدا build کنید).

شناسهٔ ناشر poorsmile است. فایل VSIX را در صفحهٔ همین ناشر در Marketplace بارگذاری کنید. شناسهٔ کامل افزونه poorsmile.ravi-markdown است.

English

Ravi Markdown brings Persian documentation into VS Code. Its reading preview offers local Vazirmatn fonts, tables, a heading outline and code copying. Edit text opens a custom Monaco editor based on Raavi's code view, with bidirectional source lines, a compact Material Symbols toolbar, safe Persian corrections, half-space, search, and native document save/undo integration. Local processing only; no account, telemetry, or remote image requests. This preview release is distributed as a VSIX, not yet published on Marketplace.