Obsidian URI یک پروتکل URI سفارشی است که توسط Obsidian پشتیبانی می‌شود و به شما امکان می‌دهد اقدامات مختلفی مانند باز کردن یادداشت یا ایجاد یادداشت را انجام دهید. Obsidian URI امکان خودکارسازی و گردش‌کارهای بین اپلیکیشنی را فراهم می‌کند. ## قالب URI URI‌های Obsidian از قالب زیر استفاده می‌کنند: ``` obsidian://action?param1=value&param2=value ``` پارامتر `action` عملی است که می‌خواهید انجام دهید. اقدامات موجود عبارتند از: - `open` برای باز کردن یادداشت. - `new` برای ایجاد یا افزودن به یادداشت موجود. - `daily` برای ایجاد یا باز کردن یادداشت روزانه. - `unique` برای ایجاد یادداشت یکتای جدید. - `search` برای باز کردن جستجو. - `choose-vault` برای باز کردن مدیریت گاوصندوق‌ها. > [!warning] کدگذاری > اطمینان حاصل کنید که مقادیر شما به درستی با کدگذاری URI رمزگذاری شده‌اند. به عنوان مثال، کاراکترهای اسلش `/` باید به صورت `%2F` و کاراکترهای فاصله باید به صورت `%20` کدگذاری شوند. > > این امر به ویژه مهم است زیرا یک کاراکتر «رزرو شده» که به درستی کدگذاری نشده باشد ممکن است تفسیر URI را مختل کند. [برای جزئیات بیشتر اینجا را ببینید](https://en.wikipedia.org/wiki/Percent-encoding). ## باز کردن یادداشت عمل `open` یک گاوصندوق Obsidian را باز می‌کند یا فایلی درون آن گاوصندوق را باز می‌کند. ### نمونه‌ها - `obsidian://open?vault=my%20vault` این گاوصندوق `my vault` را باز می‌کند. اگر گاوصندوق از قبل باز باشد، پنجره آن فعال می‌شود. - `obsidian://open?vault=ef6ca3e3b524d22f` این گاوصندوقی با شناسه `ef6ca3e3b524d22f` را باز می‌کند. - `obsidian://open?vault=my%20vault&file=my%20note` این یادداشت `my note.md` را در گاوصندوق `my vault` باز می‌کند، به شرط آنکه فایل وجود داشته باشد. - `obsidian://open?path=%2Fhome%2Fuser%2Fmy%20vault%2Fpath%2Fto%2Fmy%20note` این به دنبال هر گاوصندوقی می‌گردد که مسیر `/home/user/my vault/path/to/my note` را شامل شود. سپس بقیه مسیر به پارامتر `file` ارسال می‌شود. به عنوان مثال، اگر گاوصندوقی در `/home/user/my vault` وجود داشته باشد، این معادل تنظیم پارامتر `file` بر روی `path/to/my note` خواهد بود. > [!tip] باز کردن سرفصل یا بلوک > با کدگذاری URI مناسب، می‌توانید به یک سرفصل یا بلوک درون یادداشت پیمایش کنید. `Note%23Heading` به سرفصلی به نام "Heading" می‌رود، در حالی که `Note%23%5EBlock` به بلوکی به نام "Block" می‌رود. ### پارامترها - `vault` می‌تواند نام گاوصندوق یا شناسه گاوصندوق باشد[^1]. - `file` می‌تواند نام فایل یا مسیری از ریشه گاوصندوق به فایل مشخص‌شده باشد. اگر پسوند فایل `md` باشد، می‌توان پسوند را حذف کرد. - `path` یک مسیر مطلق سیستم فایل به یک فایل. - استفاده از این پارامتر هر دو `vault` و `file` را بازنویسی می‌کند. - این کار باعث می‌شود اپلیکیشن به دنبال خاص‌ترین گاوصندوقی بگردد که مسیر فایل مشخص‌شده را شامل شود. - سپس بقیه مسیر جایگزین پارامتر `file` می‌شود. - `prepend` به ابتدای فایل اضافه می‌کند و تلاش می‌کند ویژگی‌ها را ادغام کند. - `append` به انتهای فایل اضافه می‌کند و همچنین تلاش می‌کند ویژگی‌ها را ادغام کند. - `paneType` (اختیاری) تعیین می‌کند که یادداشت در کدام قسمت رابط کاربری باز شود. - اگر وجود نداشته باشد، آخرین زبانه فعال جایگزین می‌شود. - `paneType=tab` در زبانهٔ جدید باز می‌شود. - `paneType=split` در گروه زبانه جدید باز می‌شود. - `paneType=window` در پنجره بازشو باز می‌شود (فقط دسکتاپ). ## ایجاد یادداشت عمل `new` یادداشت جدیدی در گاوصندوق ایجاد می‌کند، به صورت اختیاری با محتوای مشخص. ### نمونه‌ها - `obsidian://new?vault=my%20vault&name=my%20note` این گاوصندوق `my vault` را باز می‌کند و یادداشت جدیدی به نام `my note` ایجاد می‌کند. - `obsidian://new?vault=my%20vault&file=path%2Fto%2Fmy%20note` این گاوصندوق `my vault` را باز می‌کند و یادداشت جدیدی در `path/to/my note` ایجاد می‌کند. ### پارامترها - `vault` می‌تواند نام گاوصندوق یا شناسه گاوصندوق باشد[^1]. مانند عمل `open`. - `name` نام فایلی که باید ایجاد شود. اگر مشخص شود، مکان فایل بر اساس تنظیمات «جای پیش‌فرض یادداشت‌ها نو» انتخاب می‌شود. - `file` یک مسیر مطلق گاوصندوق، شامل نام. در صورت مشخص شدن، `name` را بازنویسی می‌کند. - `path` یک مسیر مطلق سراسری. مشابه گزینه `path` در عمل `open` عمل می‌کند که هر دو `vault` و `file` را بازنویسی می‌کند. - `paneType` (اختیاری) تعیین می‌کند که یادداشت در کدام قسمت رابط کاربری باز شود. مانند عمل `open`. - `content` (اختیاری) محتوای یادداشت. - `clipboard` (اختیاری) استفاده از محتوای کلیپ‌بورد به جای مشخص کردن `content`. - `silent` (اختیاری) این پارامتر را اضافه کنید اگر نمی‌خواهید یادداشت جدید باز شود. - `append` (اختیاری) این پارامتر را اضافه کنید تا در صورت وجود فایل، محتوا به آن الحاق شود. - `overwrite` (اختیاری) فایل موجود را بازنویسی می‌کند در صورت وجود، اما فقط اگر `append` تنظیم نشده باشد. - `x-success` (اختیاری) ببینید [[#استفاده از پارامترهای x-callback-url]]. ## ایجاد یا باز کردن یادداشت روزانه عمل `daily` یادداشت روزانه شما را ایجاد یا باز می‌کند. افزونه [[روزنوشت‌ها]] باید فعال باشد. ### نمونه‌ها - `obsidian://daily?vault=my%20vault` این گاوصندوق `my vault` را باز می‌کند و یادداشت روزانه را ایجاد یا باز می‌کند. ### پارامترها عمل `daily` همان پارامترهای عمل `new` را می‌پذیرد. ## یادداشت یکتا عمل `unique` یادداشت یکتای جدیدی در گاوصندوق ایجاد می‌کند. افزونه [[یادداشت‌یکتاساز]] باید فعال باشد. ### نمونه‌ها - `obsidian://unique?vault=my%20vault` این گاوصندوق `my vault` را باز می‌کند و یادداشت یکتای جدیدی ایجاد می‌کند. - - `obsidian://unique?vault=my%20vault&content=Hello%20World` این گاوصندوق `my vault` را باز می‌کند و یادداشت یکتای جدیدی با محتوای `Hello World` ایجاد می‌کند. ### پارامترها - `vault` می‌تواند نام گاوصندوق یا شناسه گاوصندوق باشد[^1]. مانند عمل `open`. - `paneType` (اختیاری) تعیین می‌کند که یادداشت در کدام قسمت رابط کاربری باز شود. مانند عمل `open`. - `content` (اختیاری) محتوای یادداشت. - `clipboard` (اختیاری) استفاده از محتوای کلیپ‌بورد به جای مشخص کردن `content`. - `x-success` (اختیاری) ببینید [[#استفاده از پارامترهای x-callback-url]]. ## باز کردن جستجو عمل `search` [[جستجو]] را در گاوصندوق مشخص‌شده باز می‌کند و به صورت اختیاری عبارت جست‌وجویی را اجرا می‌کند. ### نمونه‌ها - `obsidian://search?vault=my%20vault` این گاوصندوق `my vault` را باز می‌کند و [[جستجو]] را باز می‌کند. - `obsidian://search?vault=my%20vault&query=Obsidian` این گاوصندوق `my vault` را باز می‌کند، [[جستجو]] را باز می‌کند و جستجویی برای `Obsidian` انجام می‌دهد. ### پارامترها - `vault` می‌تواند نام گاوصندوق یا شناسه گاوصندوق باشد[^1]. مانند عمل `open`. - `query` (اختیاری) عبارت جست‌وجو برای اجرا. ## باز کردن مدیریت گاوصندوق‌ها عمل `choose-vault` [[مدیریت گاوصندوق‌ها|مدیریت گاوصندوق‌ها]] را باز می‌کند. ### نمونه‌ها - `obsidian://choose-vault` ## یکپارچه‌سازی با Hook این عمل Obsidian URI برای استفاده با [Hook](https://hookproductivity.com/) طراحی شده است. ### نمونه `obsidian://hook-get-address` ### پارامترها - `vault` (اختیاری) می‌تواند نام گاوصندوق یا شناسه گاوصندوق باشد[^1]. اگر ارائه نشود، گاوصندوق فعلی یا آخرین گاوصندوق فعال استفاده می‌شود. - `x-success` (اختیاری) ببینید [[#استفاده از پارامترهای x-callback-url]]. - `x-error` (اختیاری) ببینید [[#استفاده از پارامترهای x-callback-url]]. اگر `x-success` تعریف شده باشد، این API از آن به عنوان x-callback-url استفاده می‌کند. در غیر این صورت، یک پیوند Markdown از یادداشت فعال فعلی را به عنوان URL `obsidian://open` در کلیپ‌بورد کپی می‌کند. ## استفاده از پارامترهای x-callback-url برخی نقاط انتهایی پارامترهای x-callback-url شامل `x-success` و `x-error` را می‌پذیرند. وقتی ارائه شود، Obsidian موارد زیر را به callback `x-success` ارسال می‌کند: - `name` نام فایل، بدون پسوند. - `url` آدرس URI `obsidian://` برای این فایل. - `file` (فقط دسکتاپ) آدرس URL `file://` برای این فایل. به عنوان مثال، اگر Obsidian دریافت کند `obsidian://.....x-success=myapp://x-callback-url`، پاسخ به صورت `myapp://x-callback-url?name=...&url=obsidian%3A%2F%2Fopen...&file=file%3A%2F%2F...` خواهد بود. ## قالب‌های کوتاه‌شده علاوه بر قالب‌های بالا، دو قالب «کوتاه‌شده» دیگر نیز برای باز کردن گاوصندوق‌ها و فایل‌ها در دسترس است: 1. `obsidian://vault/my vault/my note` معادل `obsidian://open?vault=my%20vault&file=my%20note` است. 2. `obsidian:///absolute/path/to/my note` معادل `obsidian://open?path=%2Fabsolute%2Fpath%2Fto%2Fmy%20note` است. ## عیب‌یابی ### ثبت Obsidian URI در ویندوز و macOS، اجرای یک‌باره اپلیکیشن باید برای ثبت پروتکل Obsidian URI بر روی رایانه شما کافی باشد. در لینوکس، این فرآیند پیچیده‌تر است: 1. اطمینان حاصل کنید که فایل `obsidian.desktop` را ایجاد کرده‌اید. [برای جزئیات بیشتر اینجا را ببینید](https://developer.gnome.org/documentation/guidelines/maintainer/integrating.html#desktop-files). 2. اطمینان حاصل کنید که فایل desktop شما فیلد `Exec` را به صورت `Exec=executable %u` مشخص کرده است. `%u` برای ارسال URIهای `obsidian://` به اپلیکیشن استفاده می‌شود. 3. اگر از نصب‌کننده AppImage استفاده می‌کنید، ممکن است نیاز باشد آن را با `Obsidian-x.y.z.AppImage --appimage-extract` باز کنید. سپس مطمئن شوید که دستورالعمل `Exec` به فایل اجرایی باز شده اشاره می‌کند. [^1]: شناسه گاوصندوق یک کد تصادفی ۱۶ کاراکتری است که به گاوصندوق اختصاص داده شده است، به عنوان مثال `ef6ca3e3b524d22f`. این شناسه برای هر پوشه در رایانه شما یکتا است. شناسه را می‌توان با باز کردن تعویض‌گر گاوصندوق و کلیک بر روی «کپی شناسه‌ی خزانه» در منوی زمینه گاوصندوق مورد نظر پیدا کرد.