Документація Obsidian відповідає стилістичним рекомендаціям, наведеним на цій сторінці. Ці рекомендації базуються на найкращих галузевих практиках, зокрема [посібнику зі стилю документації Google для розробників](<https://developers.google.com/style>) та [посібнику зі стилю Microsoft](https://learn.microsoft.com/en-us/style-guide/). Для випадків, не описаних нижче, зверніться до цих зовнішніх посібників як додаткових джерел. > [!tip]- Долучитися > Більша частина документації існувала ще до появи цього посібника зі стилю. > > Якщо ви знайдете будь-які порушення цього посібника зі стилю, будь ласка, [створіть запит](https://github.com/obsidianmd/obsidian-docs/issues/new) та надішліть pull request до [obsidianmd/obsidian-docs](https://github.com/obsidianmd/obsidian-docs). ## Термінологія та граматика ### Мовний стиль Для нашої англомовної документації рекомендується використовувати [Global English](https://docs.openedx.org/en/latest/documentors/references/doc_english_writing.html), щоб краще обслуговувати нашу світову аудиторію та сприяти [[#Переклади|перекладам]]. Це означає: - Уникати ідіом та культурно-специфічних виразів - Використовувати активний стан та пряму побудову речень - Надавати перевагу простим, загальновживаним словам замість складної термінології - Бути явними, а не підрозумівати - Для орфографічних конвенцій використовувати американську англійську (наприклад, «organize», а не «organise»). ### Терміни - Надавайте перевагу «keyboard shortcut» замість «hotkey». Використовуйте Hotkey при посиланні на конкретну функцію. - Надавайте перевагу «the Obsidian app» на мобільних пристроях та «the Obsidian application» на комп'ютері. - Надавайте перевагу «sync» або «syncing» замість «synchronise» або «synchronising». - Надавайте перевагу «search term» замість «search query». - Надавайте перевагу «heading» замість «header» при посиланні на текст, що вводить розділ. - Надавайте перевагу «maximum» замість «max» та «minimum» замість «min». ### Назви продуктів Назви продуктів Obsidian починаються з «Obsidian», наприклад «Obsidian Publish» та «Obsidian Sync». Якщо абзац стає надмірно повторюваним, ви можете використовувати скорочену форму в подальших згадках. Наприклад: _Щоб забезпечити налаштування, специфічне для пристрою, Obsidian Sync не синхронізує власні параметри. Вам потрібно налаштувати Sync для кожного зі своїх пристроїв._ ### Інтерфейс та взаємодія - Використовуйте **жирний** шрифт для позначення тексту кнопок. - Надавайте перевагу «select» замість «tap» або «click». - Для інструкцій, специфічних для мобільних пристроїв, «tap» допустимо при описі сенсорних взаємодій, оскільки «click» недоступний. - Надавайте перевагу «sidebar» замість «side bar». - Надавайте перевагу «perform» замість «invoke» та «execute» при посиланні на команди або дії. При посиланні на кілька послідовних взаємодій з інтерфейсом використовуйте символ → (U+2192). Наприклад, «**[[Налаштування]] → Додатки спільноти**». ### Нотатки, файли та теки - Використовуйте «нотатка» при посиланні на файл Markdown у сховищі. - Використовуйте «файл» при посиланні на інші розширення файлів, окрім Markdown. - Надавайте перевагу «назва нотатки» замість «заголовок нотатки». - Надавайте перевагу «активна нотатка» замість «поточна нотатка». - Надавайте перевагу «тека» замість «директорія». - Надавайте перевагу «тип файлу» замість «формат файлу», якщо тільки мова не йде конкретно про формат даних вмісту файлу. При переміщенні між нотатками використовуйте «відкрити», якщо місце призначення приховане, та «переключитися», якщо і вихідна, і цільова нотатки відкриті в окремих панелях. ### Довідкова документація для налаштувань За можливості, будь-які налаштування повинні бути задокументовані безпосередньо в Obsidian за допомогою описового тексту. Уникайте документування конкретного налаштування в довідці Obsidian, за винятком випадків, коли: - Воно потребує більш глибоких знань про те, як і коли його використовувати. - Воно часто використовується неправильно або стає предметом запитань. - Воно _суттєво_ змінює досвід користувача. Розгляньте можливість використання виноски-підказки, якщо хочете привернути увагу до конкретного налаштування. ### Терміни напрямку Використовуйте дефіс у напрямкових термінах, коли вони є прикметниками. Уникайте дефісу, коли напрямок використовується як іменник. **Рекомендовано:** - Виберіть **[[Налаштування]]** у нижньому лівому куті. - Виберіть **[[Налаштування]]** внизу ліворуч. **Не рекомендовано:** - Виберіть **[[Налаштування]]** у нижньому лівому куті (без дефісу у прикметнику в англійській). - Виберіть **[[Налаштування]]** внизу-ліворуч. Надавайте перевагу «upper-left» та «upper-right» замість «top-left» та «top-right». Не вказуйте напрямок при посиланні на налаштування. Розташування елемента керування налаштуваннями залежить від пристрою. **Рекомендовано:** - Поруч із **Pick remote vault** виберіть **Обрати**. **Не рекомендовано:** - Праворуч від **Pick remote vault** виберіть **Обрати**. При описі вертикального напрямку в елементах інтерфейсу використовуйте «вище» та «нижче» для просторових відносин. Уникайте «вгору» та «вниз», оскільки вони можуть бути неоднозначними в різних контекстах. **Рекомендовано:** - Поле пошуку з'являється вище списку файлів. - Додаткові параметри доступні нижче. **Не рекомендовано:** - Поле пошуку знаходиться вгору від списку файлів. - Інші параметри знаходяться внизу під ним. ### Інструкції Використовуйте наказовий спосіб для назв посібників, заголовків розділів та покрокових інструкцій. Наказовий спосіб є лаконічним та орієнтованим на дію, що більш зрозуміло для користувачів, які дотримуються інструкцій. - Надавайте перевагу «Налаштуйте» замість «Налаштування (як процес)» - Надавайте перевагу «Перемістіть файл» замість «Переміщення файлу» - Надавайте перевагу «Імпортуйте ваші нотатки» замість «Імпорт ваших нотаток» ### Регістр речення Надавайте перевагу *регістру речення* замість *регістру заголовка* для заголовків, кнопок та назв. При посиланні на елементи інтерфейсу завжди відповідайте регістру тексту в інтерфейсі. **Рекомендовано:** - Як Obsidian зберігає дані **Не рекомендовано:** - Як Obsidian Зберігає Дані ### Приклади Надавайте перевагу реалістичним прикладам замість безглуздих термінів. **Рекомендовано:** - `task:(call OR schedule)` **Не рекомендовано:** - `task:(foo OR bar)` ### Назви клавіш та сполучення клавіш При посиланні на клавіші та сполучення клавіш використовуйте послідовну нотацію. **Назви окремих клавіш:** При посиланні на символ на клавіатурі за назвою додайте символ у дужках одразу після назви. **Рекомендовано:** - Натисніть клавішу дефіс (-), щоб додати тире. - Використовуйте знак питання (?), щоб виконати пошук. **Не рекомендовано:** - Натисніть клавішу дефіс, щоб додати тире. - Використовуйте ?, щоб виконати пошук. - Додайте `-` перед словом. **Сполучення клавіш:** Форматуйте сполучення клавіш без пробілів навколо знака «плюс». Коли сполучення клавіш відрізняється для різних операційних систем, вкажіть обидва варіанти. **Рекомендовано:** - Натисніть `Ctrl+Z` (Windows) або `Command+Z` (macOS), щоб скасувати дію. - Натисніть `Escape`, щоб закрити це вікно. - Використовуйте `Tab`, щоб переміщуватися між полями. **Не рекомендовано:** - Натисніть `Cmd+Z`, щоб скасувати дію. - Натисніть `Ctrl + Z` (з пробілами), щоб скасувати дію. - Натисніть `Ctrl/Cmd+Z`, щоб скасувати дію. Для сполучень клавіш, однакових на всіх платформах, вказувати ОС не потрібно. Якщо ви не впевнені, чи відрізняється сполучення клавіш залежно від платформи, вкажіть ОС для надійності. Windows та Linux зазвичай використовують однакові сполучення клавіш. ### Markdown Використовуйте порожні рядки між блоками Markdown: **Рекомендовано:** ```md # Заголовок 1 Це розділ. 1. Перший пункт 2. Другий пункт 3. Третій пункт ``` **Не рекомендовано:** ```md # Заголовок 1 Це розділ. 1. Перший пункт 2. Другий пункт 3. Третій пункт ``` **Довгі тире в списках:** Використовуйте довгі тире (—) для відокремлення виділених жирним термінів від їхніх описів у маркованих списках. Не використовуйте довгі тире в простих вкладених маркованих списках з посиланнями. **Рекомендовано:** - **Меню подань** — створення, редагування та переключення подань. - **Обчислення значень** — додавання цін, підрахунок підсумків або виконання математичних операцій. **Не рекомендовано:** - [[Створити базу]] — Дізнайтеся, як створити та вбудувати базу. ### Зображення Використовуйте «**ширина** x **висота** пікселів» для опису розмірів зображень або екранів. **Приклад:** Рекомендовані розміри зображення: 1920 x 1080 пікселів. ## Структура інформації ### Типи виносок Використовуйте виноски стратегічно для виділення певних типів інформації: **Підказка** (`[!tip]-`) — Практичні поради або найкращі практики, що покращують робочий процес користувача. Використовуйте для ярликів, обхідних рішень або необов'язкової, але корисної інформації. Ці виноски за замовчуванням згорнуті. **Довідка** (`[!info]+`) — Додатковий контекст, фонова інформація або пояснення. Використовуйте, коли інформація додає розуміння, але не є необхідною для виконання завдання. Ці виноски за замовчуванням розгорнуті. **Увага** (`[!warning]+`) — Важливі застереження, що запобігають втраті даних, помилкам або непередбаченим наслідкам. Використовуйте помірно для дійсно ризикованих ситуацій. Ці виноски ніколи не повинні бути згорнутими. **Приклад** (`[!example]-`) — Загальні зауваження або додаткові деталі. Використовуйте для побічної інформації, що може бути корисною для деяких користувачів. Ці виноски за замовчуванням згорнуті. **Приклади:** ```md > [!tip]- Використовуйте сполучення клавіш > Ви можете прискорити робочий процес, запам'ятавши найбільш вживані сполучення клавіш. > [!info]+ Це платне доповнення > Для використання цієї функції потрібна платна підписка. > [!warning]+ Цю дію неможливо скасувати > Видалення сховища є незворотним. Спочатку розгляньте можливість експорту ваших нотаток. > [!example]- Розширене використання > Ви також можете налаштувати цей параметр через меню графа. ``` ### Списки vs. прозовий текст Використовуйте списки при поданні окремих елементів, що не мають сильних послідовних або причинно-наслідкових зв'язків. Використовуйте прозу та абзаци, коли елементи базуються один на одному, потребують пояснення або виграють від оповідного потоку. **Використовуйте список для:** - Набору не пов'язаних між собою функцій - Вимог до встановлення - Параметрів конфігурації - Кроків усунення несправностей **Використовуйте прозу для:** - Пояснень того, як щось працює - Робочих процесів із залежностями - Концептуальних оглядів - Рекомендацій, що потребують контексту ### Таблиці Використовуйте таблиці для порівняння функцій, версій або пов'язаних даних, де вирівнювання сприяє розумінню. Уникайте таблиць для простих списків або одноколонкових даних. **Гарний випадок використання:** | Функція | Мобільний | Комп'ютер | |---------|-----------|-----------| | Синхронізація | Так | Так | | Додатки | Ні | Так | | Теми | Обмежено | Повністю | ### Перехресні посилання Використовуйте внутрішні wiki-посилання (`[[Назва нотатки]]`) щедро, щоб допомогти користувачам переходити до пов'язаних тем. Проте уникайте надмірного посилання: - Не посилайтеся на один і той самий термін кілька разів на одній сторінці - Посилайтеся лише тоді, коли сторінка, на яку ви посилаєтеся, надає суттєвий додатковий контекст - Використовуйте описовий текст посилання, коли це корисно: `[[Назва нотатки#Розділ|описовий текст]]` **Приклад:** Перша згадка: «Дізнайтеся про [[Вступ до Obsidian Sync|Obsidian Sync]], щоб підтримувати сховище оновленим на всіх пристроях.» Подальша згадка: «Ви можете налаштувати Sync для кожного пристрою окремо.» ### Контент для конкретних платформ При документуванні функцій, що відрізняються між платформами, використовуйте заголовки розділів для організації вмісту. Використовуйте `Комп'ютер` та `Мобільний` як заголовки підрозділів для розділення інструкцій або функцій, специфічних для платформи. **Рекомендовано:** ```md ## Налаштування стрічкового меню ### Комп'ютер У версії для комп'ютера ви можете налаштувати стрічкове меню наступним чином: - Змінюйте порядок дій стрічкового меню, перетягуючи значки. - Щоб приховати певні дії, клацніть правою кнопкою миші на порожньому місці та зніміть позначку з дій, які хочете приховати. ### Мобільний У мобільній версії ви можете налаштувати стрічкове меню через налаштування: 1. Відкрийте **[[Налаштування]]**. 2. Перейдіть до **Оформлення**. 3. Натисніть **Змінити** у розділі **Налаштування стрічкового меню**. ``` > [!info]+ Коли створювати окремі розділи? > Створюйте окремі розділи лише тоді, коли вміст суттєво відрізняється. Якщо інструкції здебільшого однакові з незначними варіаціями, використовуйте вбудовані примітки. ## Значки та зображення Додавайте значки та зображення, коли вони полегшують пояснення речей, які важко описати словами, або коли потрібно показати важливі частини застосунку Obsidian. Зображення можна зберігати в теці `Attachments`. - Зображення повинно полегшувати розуміння тексту, що його супроводжує. **Приклад**: Після увімкнення додаток [[Лічильник слів]] створить новий запис у нижньому рядку стану. ![[Style-guide-zoomed-example.png#interface|300]] - Зображення повинні бути у форматі `.png` або `.svg`. - Якщо зображення виглядає занадто великим у нотатці, зменшіть його за межами Obsidian або налаштуйте його розміри, як пояснено в [[Вбудовування файлів#Вбудовування зображення в нотатку|вбудовуванні зображення в нотатку]]. - У рідкісних випадках ви можете розмістити особливо великі або складні зображення у [[Виноски#Згортувані виноски|згорнутій виносці]]. - Для спливних вікон або модальних вікон зображення повинно показувати все вікно застосунку Obsidian. ![[Style-guide-modal-example.png#interface]] ### Значки Значки [Lucide](https://lucide.dev/icons/) та власні значки Obsidian можна використовувати поряд з деталізованими елементами для надання візуального представлення функції. **Приклад:** У стрічковому меню ліворуч виберіть **Створити нове полотно** ![[lucide-layout-dashboard.svg#icon]], щоб створити полотно в тій самій теці, що й активний файл. **Рекомендації щодо значків** - Зберігайте значки в теці `Attachments/icons`. - Додавайте префікс `lucide-` перед назвою значка Lucide. - Додавайте префікс `obsidian-icon-` перед назвою значка Obsidian. **Приклад:** Значок для створення нового полотна повинен називатися `lucide-layout-dashboard`. - Використовуйте SVG-версію доступних значків. - Значки повинні мати ширину `18` пікселів, висоту `18` пікселів та товщину обведення `1.5`. Ви можете налаштувати ці параметри в SVG-даних. > [!info]- Налаштування розміру та обведення в SVG > ```html > <svg xmlns="http://www.w3.org/2000/svg" width="WIDTH" height="HEIGHT" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="STROKE-WIDTH" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-layout-dashboard"><rect width="7" height="9" x="3" y="3" rx="1"/><rect width="7" height="5" x="14" y="3" rx="1"/><rect width="7" height="9" x="14" y="12" rx="1"/><rect width="7" height="5" x="3" y="16" rx="1"/></svg> >``` - Використовуйте якір `icon` у вбудованих зображеннях, щоб налаштувати відступи навколо значка так, щоб він акуратно вирівнювався з текстом поблизу. - Значки повинні бути оточені дужками. ![[lucide-cog.svg#icon]] **Приклад**: `![[lucide-cog.svg#icon]]` ### Якірні теги зображень Якірні теги зображень доступні для додавання декоративних змін до вбудованих зображень. > [!warning] Попередження щодо динамічного відображення > Якірні теги значків не відображатимуться коректно в **динамічному відображенні.** Використовуйте **режим читання**, щоб переконатися, що якірний тег було застосовано. **Значок** `![[lucide-menu.svg#icon]]` Якірний тег значка забезпечує правильне вертикальне вирівнювання для значків, що використовуються для позначення елементів інтерфейсу. Перший значок меню використовує якірний тег ![[lucide-menu.svg#icon]], тоді як другий значок меню ( ![[lucide-menu.svg]] ) — ні. **Інтерфейс** `![[Vault picker.png#interface]]` Якірний тег інтерфейсу додає декоративну тінь навколо зображення. На першому зображенні якірний тег інтерфейсу застосовано. ![[Vault picker.png#interface]] Навпаки, до другого зображення якірний тег інтерфейсу не застосовано. ![[Vault picker.png]] **Контур** `![[Backlinks.png#outline]]` Якірний тег контуру додає тонку рамку навколо зображення. На першому зображенні якірний тег контуру застосовано. > [!tip] Зверніть увагу на нижню ліву частину зображення, щоб побачити різницю. ![[Backlinks.png#outline]] Друге зображення не має якірного тега контуру. ![[Backlinks.png]] ### Оптимізація Зображення уповільнюють час завантаження сторінки та займають цінний простір сховища [[Вступ до Obsidian Publish|Obsidian Publish]]. Оптимізація зображень дозволяє зменшити розмір файлу, зберігаючи при цьому візуальну цілісність зображення. Як зображення, так і значки повинні бути оптимізовані. > [!info] Інструменти для оптимізації зображень > Ось кілька рекомендованих програм для зменшення розміру зображень. > - **Windows:** [FileOptimizer](https://sourceforge.net/projects/nikkhokkho/) > - **macOS:** [ImageOptim](https://imageoptim.com/) > - **Linux/Unix** [Trimage](https://trimage.org) > > Ми рекомендуємо рівень оптимізації 65-75%. ## Макет ### Непрацюючі посилання Перед надсиланням Pull Request перевірте наявність непрацюючих посилань у документації перекладу, над яким ви працюєте, та виправте їх. Непрацюючі посилання можуть з'являтися з часом природним чином, тому перевірка їхньої точності допомагає підтримувати якість документації. Ви можете перевірити непрацюючі посилання за допомогою [[Додатки спільноти|додатків спільноти]] або інструментів, доступних у вашому IDE. ### Описи Ця документація редагується на GitHub та розміщується онлайн через [[Вступ до Obsidian Publish|Obsidian Publish]], що включає [[Попередній перегляд посилань у соціальних мережах#Description|описи]] для соціальних карток та інших елементів SEO. Якщо сторінка, над якою ви працюєте, не має [[Властивості|властивості]] `description`, будь ласка, додайте її. Опис повинен містити не більше 150 символів та надавати об'єктивний підсумок вмісту сторінки. **Добре**: Learn to create templates that capture and organize web page metadata automatically with Web Clipper. **Можна вдосконалити**: Learn how to create templates that automatically capture and organize metadata from web pages with Web Clipper. ### Вказівки щодо напрямків При написанні або переписуванні [[#Інструкції|інструкцій]] щодо виконання дії в застосунку обов'язково включайте кроки як для мобільної, так і для настільної версій. Якщо у вас немає доступу до мобільного або настільного пристрою, зазначте це при надсиланні Pull Request. ## Переклади Перекладайте весь вміст повністю при виконанні перекладу. Це включає, але не обмежується: - Назви нотаток - Назви тек - Псевдоніми - Назви вкладень - Альтернативний текст посилань