Canvas Card Linker

Automatically converts Obsidian Canvas text cards into notes (named after their first line), and mirrors labeled arrow connections as wikilinks inside the source note. Example: if an arrow is labeled "Critique of this claim", the source note gets a line like Critique of this claim: [[Second note]].

Everything runs on-demand via a hotkey (default Ctrl+F12 / Cmd+F12 on Mac) or a ribbon-icon menu, so it never interrupts you while typing on a card or an arrow label. Optional toggles let you re-enable background automation if you prefer.

مستندات کامل و فارسی در ادامه‌ی همین فایل آمده است 👇

پلاگین ابسیدین برای محیط Canvas، با دو کار مشخص:

1. هر کارت متنی که روی کانواس اضافه می‌کنید، خودکار به یک نوت تبدیل می‌شود. نام نوت همان سطر اول متن کارت است.
2. برچسبی که روی یک پیکان (ارتباط) بین دو کارت می‌نویسید، در نوتِ مبدأ به‌صورت لینک ویکی درج می‌شود. مثلاً اگر روی پیکان بنویسید «نقد این ادعا»، در نوتِ اول این خط اضافه می‌شود:

نقد این ادعا: [[نوت دوم]]

تغییرات نسخه ۱.۳.۳ (کارت‌های کاملاً خالی دیگر زودتر از موعد تبدیل نمی‌شوند)

ریشه‌ی مشترکِ چند مشکلِ قبلی پیدا شد: اگر پردازشِ خودکار روشن باشد (چه با سوییچِ تنظیمات، چه به‌خاطرِ شبکه‌ی ایمنیِ «شورتکات تنظیم نشده»)، ممکن است پلاگین دقیقاً همان لحظه‌ای که یک کارتِ تازه ساخته می‌شود — پیش از اینکه حتی یک حرف، از جمله علامتِ سنجاق‌کردن «.»، تایپ شده باشد — کارت را ببیند. چون کارت کاملاً خالی است، پلاگین مجبور بود با نامِ موقتِ «کارت بدون عنوان» تبدیلش کند به نوت؛ و از آن لحظه به بعد، چون کارت دیگر یک نوتِ واقعی است نه یک کارتِ متنی، حتی اگر بعداً نقطه و متنِ واقعی را تایپ کنید، ویژگیِ کارتِ سنجاق‌شده دیگر رویش اثر نمی‌کند (چون آن ویژگی فقط قبل از تبدیل‌شدن معنا دارد).

رفع شد: حالا کارتِ کاملاً خالی (یا فقط فاصله) که هنوز هیچ‌وقت تبدیل نشده، اصلاً پردازش نمی‌شود و دست‌نخورده روی کانواس می‌ماند — نه نوتی برایش ساخته می‌شود، نه نامِ الکی می‌گیرد. به‌محضِ اینکه چیزی (حتی یک نقطه) تویش تایپ شود، همان لحظه‌ی بعدی که پردازش اجرا شود (خودکار یا با شورتکات)، طبقِ قوانینِ معمول رفتار می‌کند — یعنی اگر با نقطه شروع شده باشد، سنجاق می‌ماند؛ وگرنه با همان متنِ واقعی به نوت تبدیل می‌شود.

اگه پردازشِ خودکار براتون فعاله بدونِ اینکه خودتون خواسته باشید، احتمالاً به‌خاطرِ همون شبکه‌ی ایمنیِ «شورتکاتی تنظیم نشده» است — از منوی آیکونِ نوارِ کناری (🔗) چک کنید که نوشته «✓ شورتکات تنظیم است» یا «⚠ شورتکاتی تنظیم نشده»؛ اگر حالتِ دوم بود، یک شورتکات براش تنظیم کنید تا پردازش فقط با کلیدِ خودتون اجرا بشه.

تغییرات نسخه ۱.۳.۲ (نوت‌های گیرکرده با نامِ الکی خودشان را اصلاح می‌کنند)

رفعِ نسخه‌ی ۱.۳.۱ فقط نیمی از ماجرا بود: اگر یک نوت از قبل (مثلاً زیر نسخه‌ی ۱.۳.۰، پیش از این رفع) با نامِ الکیِ «کارت بدون عنوان …» ساخته شده بود و بعداً متنِ واقعی‌اش هم نوشته شده بود، پلاگین همچنان اسمِ الکی رو دست‌نخورده نگه می‌داشت — چون این نوت اولین‌باری بود که با سیستمِ ردیابیِ عنوانِ نسخه‌ی جدید دیده می‌شد، و پلاگین برای احتیاط (تا نامِ دستیِ شما رو بی‌جهت عوض نکنه) دست بهش نمی‌زد.

رفع شد: حالا اگر نامِ فعلیِ یک نوت دقیقاً همون الگوی خودِ پلاگین برای «کارت بدون عنوان» باشه، دیگه به‌عنوانِ یک انتخابِ دستیِ کاربر در نظر گرفته نمی‌شه — چون هیچ‌کس واقعاً از قصد نوتش رو «کارت بدون عنوان ۹۰۰۴۷۸» نمی‌ذاره. در این حالت، همان اولین‌بار هم نامِ نوت با متنِ واقعیِ کارت هم‌گام می‌شه. نام‌های دستیِ واقعی (هر چیزِ دیگه) هنوز کاملاً محفوظ می‌مونن.

اگه نوت‌هایی دارید که از قبل با این اسمِ الکی گیر کرده بودن، کافیه دوباره روی همون کانواس شورتکات را بزنید — خودشان اصلاح می‌شن.

تغییرات نسخه ۱.۳.۱ (رفعِ نام‌گذاریِ الکیِ نوت‌های تازه)

نسخه‌ی ۱.۳.۰ یک باگِ جدید داشت: اگر یک کارت درست همون لحظه‌ای که هنوز متنش خالی بود پردازش می‌شد (مثلاً کارت تازه ساخته شده بود و هنوز چیزی توش تایپ نکرده بودید)، پلاگین برایش یک نوتِ موقت با نامِ «کارت بدون عنوان» به‌همراه یک رشته‌ی الکیِ حروف/عدد می‌ساخت. تا اینجا طبیعی بود — اما رفعِ باگِ «برگشتنِ نامِ دستیِ نوت» در همین نسخه، به‌اشتباه این نامِ الکی رو هم مثلِ یک تغییرِ دستیِ کاربر در نظر می‌گرفت و دیگر هیچ‌وقت اصلاحش نمی‌کرد — حتی بعد از اینکه متنِ واقعیِ کارت را کامل می‌نوشتید.

رفع شد: حالا وقتی پلاگین یک نوتِ جدید می‌سازد (چه با نامِ واقعی، چه با نامِ موقتِ «کارت بدون عنوان»)، همان لحظه نامِ استفاده‌شده را به‌عنوانِ خط‌مبنا ثبت می‌کند. پس اگر بعداً متنِ کارت کامل شود، پلاگین متوجهِ تغییر می‌شود و نامِ نوت را به‌درستی با متنِ تازه هم‌گام می‌کند — بدون اینکه به نام‌های دستیِ واقعی که خودتان بعداً روی نوت‌های دیگر گذاشته‌اید دست بزند.

تغییرات نسخه ۱.۳.۰

کارت‌های سنجاق‌شده (پیشوند نقطه). اگر سطر اول یک کارت با «.» شروع شود، آن کارت دیگر به نوت تبدیل نمی‌شود و همیشه به‌صورت کارت روی کانواس باقی می‌ماند. اگر پیکانی از یک نوت به‌سمت چنین کارتی کشیده باشید، همان ارتباط در بخش تولیدشده‌ی نوتِ مبدأ ثبت می‌شود، با این تفاوت که چون کارتِ مقصد نوت نیست و لینکی برایش وجود ندارد، متنِ کارت به‌جای لینک، داخل گیومه نوشته می‌شود:

ایده‌ها: «ایده جالب»

(نقطه‌ی ابتدای کارت فقط یک نشانه است و در متنِ نمایش‌داده‌شده حذف می‌شود.) این برای کارت‌های کوچکِ یادداشت‌گونه‌ای مناسب است که نمی‌خواهید هر کدام یک فایل جدا بشوند، ولی می‌خواهید سرِ یک نگاه در نوتِ اصلی معلوم باشد که چه کارت‌هایی به آن وصل‌اند. اگر بعداً نقطه‌ی ابتدای کارت را بردارید، همان کارت طبق قوانین معمول (خودکار یا با شورتکات) به نوت تبدیل می‌شود و ارتباط‌های ثبت‌شده هم خودش را به‌روز کرده و به‌جای متنِ داخل گیومه، لینکِ ویکی واقعی می‌شود.

این قابلیت فعلاً فقط وقتی کار می‌کند که مبدأ پیکان از قبل نوت شده باشد؛ اگر مبدأ هم خودش یک کارتِ سنجاق‌شده باشد (هنوز نوت نیست)، آن ارتباط ثبت نمی‌شود — دقیقاً مثل رفتار قبلی پلاگین برای هر کارتِ تبدیل‌نشده‌ی دیگر.

رفعِ بازگردانی نام دستیِ نوت‌ها. پیش از این، اگر سوییچ «همگام‌سازی نام نوت با سطر اول» روشن بود، هر بار که کانواس پردازش می‌شد (حتی بدون هیچ تغییری در متنِ نوت)، پلاگین نامِ فایل را دوباره برابرِ سطرِ اول تنظیم می‌کرد. نتیجه این بود که اگر خودتان از داخل ابسیدین نامِ یک نوت را دستی عوض می‌کردید، با اولین پردازشِ بعدی، نام دوباره به همان چیزی که از سطر اول ساخته می‌شد برمی‌گشت — انگار اصلاً تغییرش نداده بودید.

رفع شد: پلاگین حالا برای هر نوت به‌خاطر می‌سپارد که آخرین بار نامش را بر اساس کدام سطرِ اول تنظیم کرده. اگر سطرِ اول از آن موقع تغییر نکرده باشد ولی نامِ فایل با آن فرق داشته باشد، یعنی خودتان دستی تغییرش داده‌اید — پلاگین دیگر رویش را برنمی‌گرداند. تغییرِ نام فقط وقتی دوباره اتفاق می‌افتد که واقعاً سطرِ اولِ نوت را عوض کنید.

تغییرات نسخه ۱.۲.۰

رابط چندزبانه. پلاگین حالا زبان ابسیدین را تشخیص می‌دهد: کاربران فارسی‌زبان همان رابط فارسی را می‌بینند و بقیه‌ی کاربران دنیا رابط انگلیسی. (تا پیش از این کل رابط فقط فارسی بود، درحالی‌که پلاگین در دایرکتوری جهانی منتشر شده.)

عنوان‌گیری هوشمندِ markdown. پیش از این اگر سطر اول کارت # ادعای اصلی بود، فایل واقعاً به اسم «# ادعای اصلی» ساخته می‌شد. حالا نشانه‌گذاری‌های markdown حذف می‌شوند و عنوان تمیز استخراج می‌شود:

همچنین اگر کارت با frontmatter (بلوک ---) شروع شود، از رویش رد می‌شود و اولین سطر واقعی را برمی‌دارد — پیش از این نام فایل --- می‌شد.

جهت پیکان‌ها دیگر نادیده گرفته نمی‌شود. کانواس سه حالت دارد و هر سه اکنون درست تفسیر می‌شوند:

• پیکان معمولی → لینک در نوت مبدأ (مثل قبل).
• پیکانی که سرش برعکس است → لینک در جهت درست، نه جهت رسم.
• پیکان دوسر → لینک در هر دو نوت.
• خط بدون هیچ سرپیکانی → قابل تنظیم: در هر دو نوت، فقط جهت رسم، یا نادیده گرفته شود.

پشتیبانی از گروه‌های کانواس. اگر گزینه‌اش را روشن کنید، کارتی که داخل یک گروهِ نام‌دار قرار دارد، نام آن گروه را به‌صورت تگ در بخش تولیدشده می‌گیرد (مثلاً گروهِ «استدلال‌ها» می‌شود #استدلال-ها). گروه‌های تودرتو هم پشتیبانی می‌شوند.

پاک‌سازی نگاشت داخلی. نگاشتِ «کارت → نوت» که در تنظیمات ذخیره می‌شد بی‌نهایت رشد می‌کرد و ورودی‌های مربوط به کانواس‌های حذف‌شده هیچ‌وقت پاک نمی‌شدند. حالا هنگام بالا آمدن ابسیدین پاک‌سازی می‌شود و به رویدادهای تغییر نام و حذفِ فایل هم واکنش نشان می‌دهد (یعنی جابه‌جا کردن یک نوت یا کانواس دیگر نگاشت را خراب نمی‌کند).

بهبودهای جزئی: لینک‌های تکراری در بخش تولیدشده حذف می‌شوند، تنظیمات به سه بخش دسته‌بندی شد، و عنوان پیش‌فرض بخش ارتباط‌ها بر اساس زبان انتخاب می‌شود.

تغییرات نسخه ۱.۱.۰ (آیکون نوار کناری + منو + شبکه‌ی ایمنیِ شورتکات)

یک آیکون (🔗) به نوار کناری چپ ابسیدین اضافه شد. کلیک روی آن این منو را باز می‌کند:

• پردازش کانواس فعلی الان — همان کاری که Ctrl+F12 می‌کند، از منو.
• تعیین/تغییر شورتکات... — مستقیم می‌برد به Settings → Hotkeys (با جست‌وجوی از‌قبل‌پرشده‌ی «Canvas Card Linker») تا شورتکاتِ دلخواه‌تان را ست کنید.
• وضعیتِ فعلیِ شورتکات (✓ تنظیم است / ⚠ تنظیم نشده).
• دو سوییچِ «تبدیل خودکار کارت به نوت» و «درج خودکار لینکِ برچسبِ پیکان» — دقیقاً همان‌هایی که در تنظیمات هم هستند، برای دسترسیِ سریع‌تر.
• «باز کردنِ تنظیمات کامل پلاگین».

شبکه‌ی ایمنی: اگر برای دستورِ پردازش هیچ شورتکاتی تنظیم نشده باشد (مثلاً حذفش کرده‌اید یا هنوز وقت نکرده‌اید ستش کنید)، پلاگین به‌طور موقت هر دو حالتِ خودکار را روشن در نظر می‌گیرد — یعنی دقیقاً رفتار قدیمیِ کاملاً خودکار — تا کارکردِ اصلی پلاگین از دست نرود. به‌محضِ اینکه یک شورتکات برای دستور تنظیم کنید، این حالتِ موقت خودکار خاموش می‌شود و همه‌چیز طبق دو سوییچِ بالا (پیش‌فرض هر دو خاموش) پیش می‌رود.

تغییرات نسخه ۱.۰.۴ (فقط با شورتکات — بدون هیچ کار خودکار)

هر دو سوییچِ خودکار («تبدیل خودکار کارت به نوت» و «درج خودکار لینکِ برچسبِ پیکان‌ها») حالا پیش‌فرض خاموش هستند. پلاگین دیگر هیچ‌وقت خودش‌به‌خود چیزی روی کانواس یا نوت‌ها تغییر نمی‌دهد؛ همه‌چیز فقط وقتی اتفاق می‌افتد که شورتکات Ctrl+F12 (مک: Cmd+F12) را بزنید یا دستور «تبدیل کارت‌ها و ارتباط‌های کانواس فعلی» را از Command Palette اجرا کنید.

اگر نسخه‌ی قبلی (۱.۰.۳) را نصب کرده بودید و سوییچ «تبدیل خودکار کارت به نوت» را دستی خاموش نکرده بودید، ممکن است در تنظیماتِ ذخیره‌شده‌ی شما هنوز روشن باشد (چون مقدار قبلاً روی دیسک ذخیره شده و به‌روزرسانیِ فایل به‌تنهایی آن را عوض نمی‌کند). بعد از جایگزین‌کردن فایل‌ها، یک‌بار به Settings → Canvas Card Linker سر بزنید و مطمئن شوید هر دو سوییچِ بالا خاموش‌اند.

تغییرات نسخه ۱.۰.۳ (بازگرداندن تبدیل خودکار کارت به نوت)

در نسخه‌ی ۱.۰.۲ هر دو کار (تبدیل کارت به نوت، و درج لینکِ برچسبِ پیکان در نوت) فقط دستی/با شورتکات انجام می‌شد. اما این دو کار از نظر ریسکِ «پرش حین تایپ» فرق دارند: تبدیلِ کارت فقط وقتی کارتِ تبدیل‌نشده‌ای وجود داشته باشد چیزی می‌نویسد، در حالی که لینک‌سازیِ پیکان دقیقاً همان لحظه‌ای که روی برچسب تایپ می‌کنید هم فعال می‌شود (چون تغییرِ برچسب هم یک تغییر در فایل کانواس است).

تغییر: این دو حالا دو سوییچِ جدا هستند:

• تبدیل خودکار کارت به نوت → پیش‌فرض روشن (مثل قبل، کارت‌ها را خودکار می‌سازد).
• درج خودکار لینکِ برچسبِ پیکان‌ها → پیش‌فرض خاموش (همان چیزی که باعث پرش حین تایپِ برچسب می‌شد؛ همچنان با شورتکات Ctrl+F12 انجام می‌شود).

شورتکات Ctrl+F12 (مک: Cmd+F12) در هر حالتی هر دو کار را یک‌جا و فوری انجام می‌دهد.

تغییرات نسخه ۱.۰.۲ (رفع مشکل ریست‌شدن گراف حین ویرایش)

پردازش خودکار پس‌زمینه باعث می‌شد پلاگین مدام فایل کانواس را از بیرون بازنویسی کند، و چون ویوی زنده در این حالت مجبور می‌شود فایل را دوباره از دیسک بخواند، زوم/موقعیت گراف ریست می‌شد و اگر همان لحظه روی برچسبِ یک پیکان تایپ می‌کردید، ویرایش می‌پرید.

رفع شد: حالا پیش‌فرض پلاگین پردازش خودکار ندارد. به‌جایش یک دستور با شورتکات پیش‌فرض Ctrl+F12 (در مک: Cmd+F12) اضافه شده که هر وقت خودتان خواستید (بعد از تمام‌شدن نوشتن روی کارت یا برچسب پیکان) پردازش را اجرا می‌کند. اگر باز هم حالت خودکار قدیمی را می‌خواهید، می‌توانید آن را از Settings → Canvas Card Linker → پردازش خودکار در پس‌زمینه روشن کنید (توصیه نمی‌شود، همان مشکل بالا را دارد).

تغییرات نسخه ۱.۰.۱ (رفع باگ مهم)

در نسخه‌ی قبلی، هر بار که یک کارتِ تبدیل‌شده را بیشتر ویرایش می‌کردید، یک نوتِ تازه‌ی دیگر ساخته می‌شد (مثلاً «تست ۱»، «تست ۱ ۲»، «تست ۱ ۳»...). علتش این بود: وقتی کانواس باز است، ویوی زنده‌ی ابسیدین یک کپی از داده‌ها را در حافظه نگه می‌دارد و هر چند وقت خودش آن را روی دیسک ذخیره می‌کند؛ این کار تغییرِ پلاگین را (که کارت را به فایل تبدیل کرده بود) دوباره به حالت متنی برمی‌گرداند، و پلاگین چون حافظه‌ای نداشت، آن را دوباره «کارت جدید» تلقی کرده و نوتِ تازه می‌ساخت.

رفع شد: پلاگین حالا برای هر کارت، شناسه‌اش را به مسیر نوتِ ساخته‌شده نگاشت می‌کند و این نگاشت را ماندگار نگه می‌دارد. اگر همان کارت دوباره به‌صورت متنی دیده شود، به‌جای ساخت نوتِ جدید، فقط محتوای همان نوتِ قبلی را با متن تازه هم‌گام می‌کند.

پاک‌سازی نوت‌های تکراریِ قبلی: نوت‌هایی که نسخه‌ی قبلی به‌اشتباه ساخته (مثل «تست ۱»، «تست ۱ ۲» و...) به‌صورت خودکار حذف نمی‌شوند، چون پلاگین نمی‌داند کدام‌یک را خودتان لازم دارید. کافی‌ست به کانواس نگاه کنید ببینید هر کارت الان به کدام نوت وصل است (روی کارت کلیک راست کنید یا نامش را ببینید)، همان را نگه دارید و بقیه‌ی نسخه‌های تکراری را دستی حذف کنید.

نصب (دستی)

1. پوشه‌ی canvas-card-linker (شامل manifest.json و main.js) را کامل کپی کنید داخل:

   <مسیر گنجینه‌ی شما>/.obsidian/plugins/canvas-card-linker/
   

2. ابسیدین را ببندید و دوباره باز کنید (یا Reload کنید).
3. به Settings → Community plugins بروید، مطمئن شوید Community plugins فعال است، و Canvas Card Linker را از لیست فعال (Enable) کنید.

نیازی به Node.js یا مرحله‌ی بیلد نیست؛ main.js مستقیماً قابل اجراست.

نحوه‌ی کار

1. روی کانواس هر تعداد کارت متنی می‌سازید، متن می‌نویسید، بین‌شان پیکان می‌کشید و روی پیکان‌ها برچسب می‌نویسید (مثلاً «نقد این ادعا») — کاملاً عادی و بدون هیچ وقفه‌ای، چون پلاگین در این حین کاری به فایل کانواس ندارد.
2. هر وقت کارتان تمام شد، شورتکات Ctrl+F12 (در مک: Cmd+F12) را بزنید، یا از Command Palette دستور «تبدیل کارت‌ها و ارتباط‌های کانواس فعلی» را اجرا کنید.
3. در همین یک اجرا: همه‌ی کارت‌های متنی به نوت تبدیل می‌شوند (نام = سطر اول)، و برای هر پیکانِ برچسب‌دار، خطی مثل زیر در نوتِ مبدأ (زیر یک بخش خودکار با عنوان «## ارتباط‌ها») درج می‌شود:

   نقد این ادعا: [[نوت دوم]]
   

   یک اعلان کوچک («کانواس پردازش شد») تأیید می‌کند که کار تمام شده.
4. اگر بعداً برچسبِ پیکانی را عوض کنید، پیکانی را حذف کنید، یا سطر اول یک نوت را عوض کنید، دفعه‌ی بعد که همین شورتکات را بزنید، همه‌چیز مطابق وضعیت جدید به‌روزرسانی می‌شود.

بخش خودکار لینک‌ها بین دو نشانه‌ی مخفی (<!-- canvas-card-linker:start --> و ...:end) قرار می‌گیرد تا پلاگین بتواند فقط همان تکه را بازنویسی کند و بقیه‌ی متن نوت دست‌نخورده بماند.

اگر شورتکات Ctrl+F12 با چیز دیگری (مثلاً DevTools) تداخل داشت، از Settings → Hotkeys می‌توانید دستور «تبدیل کارت‌ها و ارتباط‌های کانواس فعلی» را جست‌وجو و شورتکاتش را عوض کنید.

تنظیمات (Settings → Canvas Card Linker)

نکات فنی و محدودیت‌ها

• پلاگین مستقیماً فایل .canvas (که یک JSON استاندارد است) را می‌خواند و می‌نویسد، نه API داخلی و مستندنشده‌ی Canvas؛ به همین دلیل با آپدیت‌های آینده‌ی ابسیدین پایدارتر است.
• محتوای کامل کارت (نه فقط سطر اول) به‌عنوان بدنه‌ی نوتِ جدید ذخیره می‌شود؛ سطر اول هم‌زمان هم عنوان فایل است و هم داخل متن باقی می‌ماند.
• فقط کارت‌های نوعِ «متنی» تبدیل می‌شوند؛ کارت‌هایی که از قبل به یک فایل یا لینک وصل‌اند دست‌نخورده می‌مانند.
• تشخیصِ «آیا شورتکاتی تنظیم شده یا نه» از یک API داخلی و مستندنشده‌ی ابسیدین (app.hotkeyManager) استفاده می‌کند. اگر این API در نسخه‌ای از ابسیدین تغییر کند، پلاگین محافظه‌کارانه رفتار می‌کند (فرض می‌کند شورتکات هست، یعنی خودکار روشن نمی‌شود) تا رفتار غیرمنتظره پیش نیاید.
• نام‌گذاری فایل‌ها کاراکترهای غیرمجاز سیستم‌فایل (\ / : * ? " < > | #) را حذف می‌کند و در صورت تکراری‌بودن نام، پسوند عددی ( 2, 3, ...) اضافه می‌شود.