Документация 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). ## Терминология и грамматика ### Языковой стиль Для нашей документации на английском языке рекомендуется использовать [глобальный английский](https://docs.openedx.org/en/latest/documentors/references/doc_english_writing.html), чтобы лучше обслуживать нашу мировую аудиторию и помогать с [[#Переводы|переводами]]. Это означает: - Избегание идиом и культурно-специфических выражений - Использование активного залога и прямых конструкций предложений - Предпочтение простых, общеупотребительных слов сложной терминологии - Явное выражение, а не подразумеваемое - Для правил написания использование американского английского (например, 'organize', а не 'organise'). ### Термины - Предпочтительно «keyboard shortcut» (сочетание клавиш) вместо «hotkey». Используйте Hotkey только при обращении к конкретной функции. - Предпочтительно «the Obsidian app» (приложение Obsidian) на мобильных устройствах и «the Obsidian application» (приложение Obsidian) на настольных. - Предпочтительно «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, если только: - Она требует более глубоких знаний о том, как и когда её использовать. - Она часто используется неправильно или вызывает вопросы. - Она _кардинально_ меняет пользовательский опыт. Рассмотрите использование выносного блока-подсказки, если хотите привлечь внимание к конкретной настройке. ### Указания направления Ставьте дефис в составных определениях направления, когда они используются как прилагательные. Избегайте дефиса, когда направление используется как существительное. **Рекомендуется:** - Выберите **[[Настройки]]** в нижнем левом углу. - Выберите **[[Настройки]]** внизу слева. **Не рекомендуется:** - Выберите **[[Настройки]]** в нижнем левом углу. (без дефиса в прилагательном) - Выберите **[[Настройки]]** в нижнем-левом. (с дефисом в существительном) Предпочтительно «верхний левый» и «верхний правый» вместо «левый верхний» и «правый верхний». Не указывайте направление при обращении к настройкам. Расположение элементов управления настройками зависит от устройства. **Рекомендуется:** - Рядом с **Выбрать удалённое хранилище** нажмите **Выбрать**. **Не рекомендуется:** - Справа от **Выбрать удалённое хранилище** нажмите **Выбрать**. При описании вертикального направления в элементах интерфейса используйте «над» и «под» для пространственных отношений. Избегайте «вверх» и «вниз», так как они неоднозначны в различных контекстах. **Рекомендуется:** - Поле поиска отображается над списком файлов. - Дополнительные параметры доступны ниже. **Не рекомендуется:** - Поле поиска находится выше списка файлов. - Ещё параметры расположены внизу ниже. ### Инструкции Используйте повелительное наклонение для названий руководств, заголовков разделов и пошаговых инструкций. Повелительное наклонение лаконично и ориентировано на действие, что более понятно для пользователей, следующих инструкциям. - Предпочтительно «Настройте» вместо «Настройка» - Предпочтительно «Переместите файл» вместо «Перемещение файла» - Предпочтительно «Импортируйте заметки» вместо «Импортирование заметок» ### Регистр букв Предпочтительно *регистр предложения* вместо *регистра заголовка* для заголовков, кнопок и названий. При ссылке на элементы интерфейса всегда соблюдайте регистр текста в интерфейсе. **Рекомендуется:** - Как 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]- Расширенное использование > Вы также можете настроить этот параметр через меню графа. ``` ### Списки и текст Используйте списки при представлении отдельных элементов, не имеющих сильных последовательных или причинно-следственных связей. Используйте текст и абзацы, когда элементы основываются друг на друге, требуют объяснения или выигрывают от повествовательного изложения. **Используйте список для:** - Набора несвязанных функций - Требований к установке - Параметров конфигурации - Шагов по устранению неполадок **Используйте текст для:** - Объяснений того, как что-то работает - Рабочих процессов с зависимостями - Концептуальных обзоров - Рекомендаций, требующих контекста ### Таблицы Используйте таблицы для сравнения функций, версий или связанных данных, где выравнивание помогает пониманию. Избегайте таблиц для простых списков или данных в одном столбце. **Хороший пример использования:** | Функция | Мобильные | Настольные | |---------|-----------|------------| | Синхронизация | Да | Да | | Плагины | Нет | Да | | Темы | Ограниченно | Полностью | ### Перекрёстные ссылки Широко используйте внутренние 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]]` Якорный тег icon обеспечивает правильное вертикальное выравнивание значков, используемых для обозначения элементов интерфейса. Первый значок меню использует якорный тег ![[lucide-menu.svg#icon]], а второй значок меню ( ![[lucide-menu.svg]] ) — нет. **Интерфейс** `![[Vault picker.png#interface]]` Якорный тег interface добавляет декоративную тень вокруг изображения. На первом изображении якорный тег interface применён. ![[Vault picker.png#interface]] Для сравнения, на втором изображении якорный тег interface не применён. ![[Vault picker.png]] **Контур** `![[Backlinks.png#outline]]` Якорный тег outline добавляет тонкую рамку вокруг изображения. На первом изображении якорный тег outline применён. > [!tip] Обратите внимание на нижний левый угол изображения, чтобы увидеть разницу. ![[Backlinks.png#outline]] На втором изображении якорный тег outline отсутствует. ![[Backlinks.png]] ### Оптимизация Изображения замедляют загрузку страницы и занимают ценное место в хранилище [[Введение в Obsidian Publish|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]], который включает [[Превью ссылок в социальных сетях#Описание|описания]] для социальных карточек и другие элементы [[SEO]]. Если на странице, над которой вы работаете, нет [[Свойства|свойства]] `description`, пожалуйста, добавьте его. Описание должно содержать не более 150 символов и предоставлять объективное резюме содержимого страницы. **Хорошо**: Узнайте, как создавать шаблоны для автоматического сбора и организации метаданных веб-страниц с помощью Web Clipper. **Можно улучшить**: Узнайте, как создавать шаблоны, которые автоматически собирают и организуют метаданные веб-страниц с помощью Web Clipper. ### Направления При написании или переработке [[#Инструкции|инструкций]] о том, как выполнить действие в приложении, обязательно включайте шаги как для мобильной, так и для настольной версий. Если у вас нет доступа к мобильному или настольному устройству, пожалуйста, укажите это при отправке Pull Request. ## Переводы При выполнении перевода переводите весь контент полностью. Это включает, но не ограничивается: - Названия заметок - Названия папок - Псевдонимы - Названия вложений - Альтернативный текст ссылок