--- title: Руководство по OBSIDIAN для технического писателя sidebar_position: 3 doc_rev: nmqc8uf doc_rev_of: 6ef83ebeb389edda71f4cd4c71d2c0262299fd5c6ea5a5e5c6dc35d98473fbb0 doc_rev_at: "2026-09-28" keywords: [nmqc8uf] --- # Документация Taiga IoT в Obsidian ### Описание системы **Принцип работы:** Пишите текст в Obsidian, отправляете его в GitLab → через несколько минут статья появляется на **внутреннем** сайте. Есть два сайта. **внутренний сайт** (сюда попадает ваша правка): **https://95.183.13.164.sslip.io:3002/** Это не открытая страница. Браузер сначала предупредит, что сертификат «ненадёжный» — так и задумано, сертификат пока самоподписанный. Нажмите «Дополнительно» → «Перейти на сайт». Потом откроется вход: логин и пароль выдаёт админ. Кнопка **Log out** в шапке сайта завершает сессию. И **публичный сайт** для читателей снаружи **http://95.183.13.164:3003/** Ваш push его **не обновляет**. Туда админ выпускает отдельную версию (тег `docs-*`) и только то, что разрешено в списке публикации. **Рабочей папкой является клон репозитория** из **Gitlab**. У одного изделия может быть несколько репозиториев: документация (`docs`), software, firmware. Каждый клонированный репо- это отдельная папка на диске и отдельное хранилище Obsidian. Открывайте ту, которую правите. --- ## Часть A. Один раз настроить компьютер ### A1. Установить программы 1. Установите **Obsidian**: https://obsidian.md 2. Установите **Git for Windows**: https://git-scm.com (нужен, чтобы отправлять статьи в GitLab) После установки Git **закройте и снова откройте** Obsidian и PowerShell. Проверка: откройте PowerShell (`Win + R`, введите `powershell`) и выполните: ```text git --version ``` Должна появиться строка с номером версии. ![ВерсияГита](/img/Git-version.png) ### A2. Доступ в GitLab Обычно достаточно, чтобы админ один раз настроил папку продукта и вход в Git. **Токен самому создавать не обязательно.** Если push не работает — позовите админа. **Проверка доступа к репозиторию:** 1. Откройте корпоративный GitLab: **https://gitlab.taigaiot.com** (логин вам выдали). ![ГитлабСтарт](/img/GitLabStart.png) 2. Зайдите в Projects и найдите группу с которой будете работать (например taiga_docs/ToesNode, репозиторий "Software"). ![](img/{B7D6DF8A-B180-4557-8D37-F17CF38A1E0D}.png) Если репозитория продукта не видно — позовите админа, это вопрос доступа, не Obsidian. --- ### A2.5. Создание репозитория в Gitlab Чтобы создать репозиторий зайдите в группу в которой будет лежать репозиторий: Нажмите **"Create project"** ![](img/{195C556C-0C45-4746-81A4-171CAB9F9DF5}.png) Далее **"Create blank project"** ![](img/{6AAA3849-7223-4775-B3AE-50D151B7BF8D}.png) После, на странице создания репозитория в поле "**Project name**" введите название репозитория (подчёркнуто красной линией). Ниже выберите "**Internal**" области выделенной оранжевым (если недоступно оставьте как есть). Уберите галочку с "**Initialize repository with a README**". ### A3. Клонировать репозиторий продукта Вся работа идёт в репозитории **конкретного продукта**, не в общем репозитории сайта. Пример для документации test-auth (`taiga_docs/test-auth`): 1. Откройте репозиторий продукта в GitLab. Скопируйте адрес **из строки браузера**. ![](img/link-repo.png) 2. `Win + R` → `powershell`. ![](/img/pow-win-r.png) 3. В консоли: ```text cd \ git clone "ссылка на репозиторий" ``` ![](/img/git-clone.png) Если вдруг вылезает окно с ошибкой авторизации, такого вида: ![](img/{73043E9D-DFEC-48A5-8EFA-1F0BA3CA4778}.png) То вставьте в консоль эту команду: ```bash git -c credential.helper= clone "скопированная ссылка на репозиторий" ``` Это не ошибка, вас просто просят авторизоваться. После появиться два последовательных окна, где нужно будет ввести свой логин и пароль от корпоративного Gitlab: ![](img/username.png)![](img/password.png) Рядом с диском `C:` появится папка (именем вашего репозитория). Чтобы не путать несколько репозиториев одного изделия, можно сразу переименовать папку, например в `taigabadgelw-docs`. Дальше открываете **её**. ### A3.5. Добавление обязательного скрипта Чтобы ваш репозиторий вообще смог отправиться на сайт нужно добавить в с клонированную папку файл. На компьютере в папке которую вы склонировали создайте текстовый файл (**ПКМ**--> **создать текстовый документ**). Затем, **ПКМ**--> **Переименовать**, нажмите `Ctrl+A`, а после `delete` Назовите текстовый документ так: ``` .gitlab-ci.yml ``` Откройте файл и вставьте следующий текст: ```yaml include: - project: 'taiga_docs/taigadocs/taigadocs-internal' ref: main file: '/ci/product-trigger.gitlab-ci.yml' ``` Сохраните. --- ### A4. Открыть проект в Obsidian 1. Запустите Obsidian. 2. Нажмите **«Открыть папку как хранилище»**. ![StartMenuObs](/img/start-menu-obsidian.png) 3. Укажите склонированную папку продукта, например `C:/taigabadgelw-docs`. ![](/img/vibor-dir.png) Обязательно нажмите **«Выбор папки»**. Слева появится дерево файлов. ![](/img/tree-project.png) Облачный Sync от Obsidian Inc. **не включайте.** Синхронизация здесь это плагин Git, часть C. Каждый новый продукт (и каждый репозиторий docs / software / firmware) — отдельная папка и отдельное хранилище. Плагины из A5 ставятся в каждом хранилище заново. ### A5. Плагины Путь: шестерёнка **Настройки** (слева внизу) → **Сторонние плагины** → разрешить сторонние плагины → **Обзор**. ![](/img/Plugins.png) | Что искать | Зачем | | --- | --- | | **Editing Toolbar** | кнопки: жирный, заголовки, таблицы | | **Drawio** | схемы | | **Copilot** | правка текста нейросетью внутри Obsidian | | **Git** | отправка написанного в GitLab. Без него часть C из Obsidian не работает | У каждого: **Установить** → **Включить**. --- ## Часть B. Как писать документацию Репозиторий продукта уже подключён к сайту. Отдельная папка `docs` внутри клона **не нужна** любой обычный `.md` в корне хранилища (или во вложенных папках) после push попадает на внутренний сайт в раздел этого продукта. Служебные файлы (`.gitlab-ci.yml`, папка `.obsidian`) статьями не являются. Не правьте их! ### B1. Как создать раздел (папку) 1. Слева в дереве: ПКМ → новая папка. 2. Имя файла статьи — **латиницей**, например `overview.md`. Так проще ссылки. 3. Имя папки может быть русским, если в этом продукте уже так принято (например `Интеграция`). Новую папку проще тоже назвать латиницей (`installation`): в ссылке придётся писать имя папки символ в символ. 4. Русское название раздела для читателя задаётся в статье, поле `title` (шаг B2), а не именем папки. ### B2. Как создать статью 1. В нужной папке: ПКМ → новая заметка. Имя латиницей: `overview.md`, `mounting.md`. 2. В начале файла: ```md --- title: Название на русском sidebar_position: 3 --- # Заголовок Текст… ``` - `title` — название страницы. Его же сайт показывает в меню, если нет `sidebar_label`. - `sidebar_position` — порядок в меню. Меньше число — выше пункт. - `sidebar_label` пишите только если подпись в меню должна отличаться от `title`. Пустую строку `sidebar_label: ''` **не оставляйте** — пункт меню ломается. Номер версии текста (`doc_rev`) вы **не** пишете. Его считает сборка сайта. На странице статьи есть блок с этим номером и кнопка **Копировать**. По номеру статью можно найти поиском. В файле в Obsidian этого номера обычно нет — это нормально. ### B3. Как создать таблицу Удобно кнопками **Editing Toolbar** или так: ```md | Параметр | Значение | |----------|----------| | Частота | 868 МГц | | Питание | 3.6 В | ``` Внутри таблицы **не оставляйте пустых строк**. ![](/img/table.png) Столбцы и строки можно добавить, наведя курсор на край таблицы: ![](/img/add-table.png) ### B4. Как вставить картинку Два рабочих способа. Оба после публикации открываются на сайте. **Способ 1 —** Перетащите картинку в заметку Вставленная картинка примет такой исходный вид. ```md ![[photo.png]] ``` **Способ 2 — сразу Markdown.** Положите файл в папку `img` **рядом со статьёй** и напишите: ```md ![](./img/photo.png) ``` ![](/img/img-dir.png) Пример, как это выглядит в тексте: ![](/img/visual-png.png) Картинка пути вида `![](/img/photo.png)`, **не сработает**: так сайт ищет файл в своей общей папке картинок, а не в статье. Сборка остановится. **Не делайте так** ### B5. Как вставить PDF и другие файлы в статью Просто перетащите файл в статью. Вставка, например pdf файла выглядит так. ```md ![[manual.pdf]] ``` На сайте появится окно просмотра и ссылка «Скачать PDF». Конкретную страницу из файла можно указать так: `![[manual.pdf#page=3]]`. GitLab сам перепишет эту вставку в вид, который понимает сайт. Если переписывание попало в репозиторий, после push сделайте **Pull** (часть C1). **Вложения без ссылки из статьи.** Если в папке лежат pdf, docx, hex и т.п., а в статьях они не используются, сайт сам сделает страницу **Файлы** в этом разделе и кнопку «Скачать всё архивом». Это появляется только на сайте, в Obsidian таких страниц не будет- их создавать не нужно. ### B6. Как делать ссылки на другие статьи Ссылка- кликабельный текст на другую статью. **Если статья на которую ссылаетесь находиться в папке с редактируемой статьёй**, то пишется так: ```md [текст ссылки](./название-файла.md) ``` **Но если статья на которую ссылаетесь находиться вне папке с редактируемой статьёй**, то ссылка пишется так: ``` [текст ссылки](../название-файла.md) ``` Обратите внимание, что перед `/` слэшем в этом варианте две точки Ссылки вида `[[другая-статья]]`(квадратные скобки) на сайте **не откроются**. **Проверка:** в Obsidian откройте превью и кликните ссылку. ### B7. Как создать подсказку ![](/img/tip.png) ```md :::tip Ваш текст ::: ``` :::tip Ваш текст ::: Такие же блоки: `:::note`, `:::info`, `:::warning`, `:::danger`. ### B8. Как создавать и править схему (draw.io) 1. Нужен плагин **Drawio** (часть A5). Для того чтобы создавать и редактировать схемы прямо в obsidian нужно установить **offline editor** Зайдите в **настройки** плагина Drawio: ![](img/20261028134840.png) Нажмите **install**. 2. ПКМ в дереве → папка `diag`. 3. ПКМ по `diag` → **new drawio diagram**. ![](/img/diag-step2.png) 4. Перед сохранением переименуйте вкладку (ПКМ по `Untitled…` → **Переименовать**), чтобы исходник не потерялся. ![](/img/diag-rename.png) 5. **File** → **Export as** → **SVG**. ![](/img/diag-step4.png) 6. Включите **Include a copy of my diagram** — внутри SVG останется исходник, его можно открыть снова. ![](/img/diag-step5.png) 7. Save в папку `diag` или рядом со редактируемой статьёй в папке. ![](/img/diag-step6.png) **Чтобы вставить в статью просто перетащите файл из дерева в редактируемое поле** Или можно прописать руками: ```md ![](./diag/name.svg) ``` или `![[name.svg]]`. SVG GitLab кладёт в `diag/`. Чтобы поправить схему: откройте исходник в `diag`, отредактируйте, экспортируйте SVG заново тем же именем. ### B9. Нейросеть внутри Obsidian Нужен плагин **Copilot** из части A5. Включите его. Слева появится значок, нажмите его: ![](/img/click-copilot.png) Выберите модель и `Configure`: ![](/img/copilot1.png) ![](/img/copilot2.png) После установки нажмите `Done`. ![](/img/copilot3.png) Как править абзац: 1. Откройте статью. 2. Выделите текст. 3. `Ctrl+P` → команда вроде `Copilot: Add selection to chat context`. 4. Напишите, что сделать, например: `Сделай текст понятнее, сохрани Markdown и frontmatter, не выдумывай факты.` 5. Примите правку. Если плагин просит ключ и не отвечает- позовите админа. --- ## Часть C. Отправить работу и увидеть её на сайте ### C1. Что такое Commit, Push и Pull **Commit** — слепок правок на вашем компьютере. Пока не сделан push, сайт о них не знает. **Push** — отправка этих слепков в GitLab. После push запускается сборка сайта. **Pull** — забрать с GitLab то, чего ещё нет у вас. Нужен, когда push отклоняют: кто-то (часто сам GitLab) уже записал в репозиторий новые коммиты. После вашего push GitLab может сам добавить коммит, который превращает `![[картинка]]` и `![[файл.pdf]]` в вид, который понимает сайт. В истории GitLab это сообщение вроде `chore(docs): convert Obsidian image embeds`. Это не ошибка и не чужая правка текста. Перед следующим редактированием нажмите **Pull**, чтобы этот коммит оказался у вас. Если такого коммита в репозитории нет, а на сайте картинки уже нормальные — тоже нормально: иногда переписывание делает только сборка сайта, без записи обратно в ваш репозиторий. Номер `doc_rev` в ваш файл в Obsidian GitLab **не** дописывает. Его видно на странице статьи на сайте после сборки. **Commit-and-sync** в плагине Git делает commit и push одной кнопкой. Для репозитория продукта этого достаточно. Галочка **Update submodules** техпису не нужна — она про общий репозиторий сайта, им занимается админ. ### C2. Через Obsidian 1. `Ctrl+P` → `Git: Open source control view`. 2. Откроется панель исходников (кнопка на рисунке ниже). 3. Вместо текста `vault backup: {{date}}` напишите, **что** изменили. Пустой комментарий не оставляйте. ![](/img/git-btn.png) 4. **Commit** (зелёная кнопка), затем **Push** (красная). 5. Подождите несколько минут. Сборка сайта — это не мгновенное сохранение: GitLab забирает статью и заново собирает внутренний сайт. Если в статье нет ошибок из части D, она появится по адресу из начала этой инструкции. Подробнее в C4. Если push отклонён и вылезло окно как на рисунке: ![](/img/need-pull.png) нажмите **Pull** (оранжевая кнопка), дождитесь окончания и снова **Push**. Если Git пишет про конфликт — не выбирайте файлы наугад, позовите админа. ### C3. Запасной вариант (PowerShell) Если кнопки Obsidian Git не работают — позовите админа или в PowerShell: ```powershell cd C:/"папка продукта" git status git add . git commit -m "docs: краткое описание правки" git push origin main ``` Текст после `-m` — комментарий к коммиту. Если Git спрашивает пароль — позовите админа. Проверка: GitLab → репозиторий продукта → **Commits**. Ваш коммит есть. Рядом может лежать коммит GitLab из C1 — это нормально. ### C4. Посмотреть на сайте 1. Подождите, пока сборка закончится. Обычно это несколько минут, иногда дольше, если сервер занят другой сборкой. 2. Откройте **https://95.183.13.164.sslip.io:3002/** Предупреждение сертификата → «Дополнительно» → перейти. Войдите, если спросит логин. 3. Найдите статью в меню. Обновите страницу, если она была открыта раньше (Ctrl+F5). На странице статьи есть: - поиск над деревом слева; - скачивание этой статьи файлом `.md`; - меню **Другое** → сохранение страницы в PDF через печать браузера; - история изменений статьи; - номер `doc_rev` и кнопка **Копировать**; - в разделах с «осиротевшими» вложениями — страница **Файлы** и скачивание архивом. Если статьи нет — напишите админу: какой продукт, во сколько был push, виден ли коммит в GitLab. Не проверяйте правку по адресу `:3003`: публичный сайт от вашего push не меняется. Туда статья попадёт только после выпуска админом (и только если продукт разрешён к публикации). --- ## D. Что нельзя писать | Нельзя | Нужно | | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | `[[другая-статья]]` (*сайт не воспринимает такой синтаксис*) | `[текст](./drugaya-statya)` | | `![](/img/photo.png)` для картинки продукта | `![[photo.png]]`(обычная вставка) или `![](./img/photo.png)` | | Пустой `sidebar_label: ''` | Не писать это поле | | Угловые скобки «меньше» `"<"` и «больше» `">"` в тексте статьи | Не писать их. Сайт собирает страницу как код и падает на таких скобках. Для сравнения напишите словами или знак «≤» | | Руками выдумывать или править `doc_rev` | Не писать это поле. Номер появляется на сайте после сборки | `![[photo.png]]` и `![[file.pdf]]` писать **можно**. Раньше в этой инструкции было наоборот — тогда сайт ещё не умел их принимать. --- ## Чеклист перед концом работы - [ ] Открыта папка продукта, не `C:/taiga-docs` - [ ] У статьи есть `title` - [ ] Картинка лежит в репозитории и вставлена способом из B4 - [ ] Commit с понятным сообщением и Push (или команды из C3) - [ ] Если push отклонили — Pull, затем Push ещё раз - [ ] Коммит виден в GitLab - [ ] Статья открывается на **https://95.183.13.164.sslip.io:3002/** после входа --- ## Если что-то не получается | Проблема | Кому писать | | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | Нет доступа в GitLab, push просит пароль, push отклонён и Pull не помогает | админ GitLab | | Коммит в GitLab есть, на внутреннем сайте статьи нет | админ сервера: продукт, время push, ссылка на коммит | | На `:3003` старая или неполная документация | это публичный сайт. Его обновляет админ отдельным выпуском, не ваш push | | Не ставится или не виден плагин Git | админ | | Нейросеть не отвечает | админ — ключ Copilot | | Браузер не пускает на сайт из‑за сертификата | это предупреждение самоподписанного сертификата. «Дополнительно» → перейти на сайт. Если после этого крутится вход и пароль не подходит — админ | ## Что может сломать сборку После Push GitLab собирает сайт. Если в статье ошибка — сборка **красная**, статья на внутреннем сайте не обновится. В логе failed job будет написано крупно, что не так (например `ФАЙЛ «…» НЕ НАЙДЕН` или `ССЫЛКА НА НЕСУЩЕСТВУЮЩУЮ СТАТЬЮ`). Ниже — частые причины. Лучше проверить это в Obsidian **до** Push. ### 1. Картинка или PDF вставлены, а файла нет в репозитории В тексте есть `![[photo.png]]` или `![[manual.pdf]]`, а самого файла нет в папке продукта — или он не попал в Commit/Push. **Как проверить:** в дереве слева файл с тем же именем виден рядом со статьёй (или в `img/` / `files/`). В панели Git в изменениях есть и статья, и этот файл. **Что сделать:** вставить файл заново, дать понятное имя (не оставлять `Pasted image …`), Commit и Push ещё раз. Имя в `![[…]]` должно совпадать с именем файла буква в букву. ### 2. Ссылка на статью, которой нет Написали `[текст](./overview)`, а файла `overview.md` рядом нет (опечатка, другое имя, статья в другой папке). **Как проверить:** в превью Obsidian кликните ссылку — должна открыться заметка. В ссылке путь без `.md`, относительно текущей статьи. **Нельзя** писать ссылку так: `[[overview]]` (две квадратных скобки). Так Obsidian связывает заметки у себя на компьютере; сайт такие ссылки не открывает. Нужно только `[текст](./overview)`. ### 3. PDF или другой файл через обычную ссылку Нельзя: ```md [скачать](./manual.pdf) ``` Нужно (как в B5): ```md ![[manual.pdf]] ``` Обычная ссылка на `.pdf` / `.docx` / `.zip` ломает сборку: система принимает файл за страницу документации. ### 4. Картинка продукта «с корня сайта» **Нельзя:** `![](/img/photo.png)` — ищется общая папка сайта, не ваш продукт. **Нужно:** `![[photo.png]]` или `![](./img/photo.png)` в папке `img` рядом со статьёй. ### 5. Перед Push - [ ] У всех `![[…]]` файлы лежат в vault и видны в Git вместе со статьёй - [ ] Ссылки на статьи открываются в Obsidian - [ ] Нет `[текст](./файл.pdf)` — только `![[файл.pdf]]` - [ ] Нет `![](/img/…)` для картинок продукта - [ ] Нет ссылок вида `[[имя заметки]]` - если заметки, то только `[текст](./файл)` Если Push уже ушёл и pipeline красный: GitLab → продукт → failed job → в логе строки про файл или ссылку → исправить у себя → снова Commit + Push.