Документация 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) и выполните:

git --version

Должна появиться строка с номером версии.

A2. Доступ в GitLab

Обычно достаточно, чтобы админ один раз настроил папку продукта и вход в Git.
Токен самому создавать не обязательно. Если push не работает — позовите админа.

Проверка доступа к репозиторию:

1. Откройте корпоративный GitLab: https://gitlab.taigaiot.com (логин вам выдали).

2. Зайдите в Projects и найдите группу с которой будете работать (например taiga_docs/ToesNode, репозиторий "Software").

Если репозитория продукта не видно — позовите админа, это вопрос доступа, не Obsidian.

---

A2.5. Создание репозитория в Gitlab

Чтобы создать репозиторий зайдите в группу в которой будет лежать репозиторий: Нажмите "Create project"

Далее "Create blank project" После, на странице создания репозитория в поле "Project name" введите название репозитория (подчёркнуто красной линией). Ниже выберите "Internal" области выделенной оранжевым (если недоступно оставьте как есть). Уберите галочку с "Initialize repository with a README".

A3. Клонировать репозиторий продукта

Вся работа идёт в репозитории конкретного продукта, не в общем репозитории сайта.

Пример для документации test-auth (taiga_docs/test-auth):

1. Откройте репозиторий продукта в GitLab. Скопируйте адрес из строки браузера.

2. Win + R → powershell.

3. В консоли:

cd \
git clone "ссылка на репозиторий"

Если вдруг вылезает окно с ошибкой авторизации, такого вида:

То вставьте в консоль эту команду:

git -c credential.helper= clone "скопированная ссылка на репозиторий"

Это не ошибка, вас просто просят авторизоваться. После появиться два последовательных окна, где нужно будет ввести свой логин и пароль от корпоративного Gitlab:

Рядом с диском C: появится папка (именем вашего репозитория). Чтобы не путать несколько репозиториев одного изделия, можно сразу переименовать папку, например в taigabadgelw-docs. Дальше открываете её.

A3.5. Добавление обязательного скрипта

Чтобы ваш репозиторий вообще смог отправиться на сайт нужно добавить в с клонированную папку файл. На компьютере в папке которую вы склонировали создайте текстовый файл (ПКМ--> создать текстовый документ). Затем, ПКМ--> Переименовать, нажмите Ctrl+A, а после delete

Назовите текстовый документ так:

.gitlab-ci.yml

Откройте файл и вставьте следующий текст:

include:
  - project: 'taiga_docs/taigadocs/taigadocs-internal'
    ref: main
    file: '/ci/product-trigger.gitlab-ci.yml'

Сохраните.

---

A4. Открыть проект в Obsidian

1. Запустите Obsidian.
2. Нажмите «Открыть папку как хранилище».

3. Укажите склонированную папку продукта, например C:/taigabadgelw-docs.

Обязательно нажмите «Выбор папки».

Слева появится дерево файлов.

Облачный Sync от Obsidian Inc. не включайте. Синхронизация здесь это плагин Git, часть C.

Каждый новый продукт (и каждый репозиторий docs / software / firmware) — отдельная папка и отдельное хранилище. Плагины из A5 ставятся в каждом хранилище заново.

A5. Плагины

Путь: шестерёнка Настройки (слева внизу) → Сторонние плагины → разрешить сторонние плагины → Обзор.

Что искать	Зачем
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. В начале файла:

---
title: Название на русском
sidebar_position: 3
---

# Заголовок

Текст…

• title — название страницы. Его же сайт показывает в меню, если нет sidebar_label.
• sidebar_position — порядок в меню. Меньше число — выше пункт.
• sidebar_label пишите только если подпись в меню должна отличаться от title. Пустую строку sidebar_label: '' не оставляйте — пункт меню ломается.

Номер версии текста (doc_rev) вы не пишете. Его считает сборка сайта. На странице статьи есть блок с этим номером и кнопка Копировать. По номеру статью можно найти поиском. В файле в Obsidian этого номера обычно нет — это нормально.

B3. Как создать таблицу

Удобно кнопками Editing Toolbar или так:

| Параметр | Значение |
|----------|----------|
| Частота  | 868 МГц  |
| Питание  | 3.6 В    |

Внутри таблицы не оставляйте пустых строк.

Столбцы и строки можно добавить, наведя курсор на край таблицы:

B4. Как вставить картинку

Два рабочих способа. Оба после публикации открываются на сайте.

Способ 1 — Перетащите картинку в заметку

Вставленная картинка примет такой исходный вид.

![[photo.png]]

Способ 2 — сразу Markdown. Положите файл в папку img рядом со статьёй и напишите:

![](./img/photo.png)

Пример, как это выглядит в тексте:

Картинка пути вида ![](/img/photo.png), не сработает: так сайт ищет файл в своей общей папке картинок, а не в статье. Сборка остановится. Не делайте так

B5. Как вставить PDF и другие файлы в статью

Просто перетащите файл в статью.

Вставка, например pdf файла выглядит так.

![[manual.pdf]]

На сайте появится окно просмотра и ссылка «Скачать PDF».

Конкретную страницу из файла можно указать так:

![[manual.pdf#page=3]].

GitLab сам перепишет эту вставку в вид, который понимает сайт. Если переписывание попало в репозиторий, после push сделайте Pull (часть C1).

Вложения без ссылки из статьи. Если в папке лежат pdf, docx, hex и т.п., а в статьях они не используются, сайт сам сделает страницу Файлы в этом разделе и кнопку «Скачать всё архивом». Это появляется только на сайте, в Obsidian таких страниц не будет- их создавать не нужно.

B6. Как делать ссылки на другие статьи

Ссылка- кликабельный текст на другую статью.

Если статья на которую ссылаетесь находиться в папке с редактируемой статьёй, то пишется так:

[текст ссылки](./название-файла.md)

Но если статья на которую ссылаетесь находиться вне папке с редактируемой статьёй, то ссылка пишется так:

[текст ссылки](../название-файла.md) 

Обратите внимание, что перед / слэшем в этом варианте две точки

Ссылки вида [[другая-статья]](квадратные скобки) на сайте не откроются. Проверка: в Obsidian откройте превью и кликните ссылку.

B7. Как создать подсказку

:::tip
Ваш текст
:::

подсказка

Ваш текст

Такие же блоки: :::note, :::info, :::warning, :::danger.

B8. Как создавать и править схему (draw.io)

1. Нужен плагин Drawio (часть A5).

Для того чтобы создавать и редактировать схемы прямо в obsidian нужно установить offline editor Зайдите в настройки плагина Drawio:

Нажмите install.

2. ПКМ в дереве → папка diag.
3. ПКМ по diag → new drawio diagram.

4. Перед сохранением переименуйте вкладку (ПКМ по Untitled… → Переименовать), чтобы исходник не потерялся.

5. File → Export as → SVG.

6. Включите Include a copy of my diagram — внутри SVG останется исходник, его можно открыть снова.

7. Save в папку diag или рядом со редактируемой статьёй в папке.

Чтобы вставить в статью просто перетащите файл из дерева в редактируемое поле Или можно прописать руками:

![](./diag/name.svg)

или ![[name.svg]]. SVG GitLab кладёт в diag/.

Чтобы поправить схему: откройте исходник в diag, отредактируйте, экспортируйте SVG заново тем же именем.

B9. Нейросеть внутри Obsidian

Нужен плагин Copilot из части A5. Включите его. Слева появится значок, нажмите его:

Выберите модель и Configure:

После установки нажмите Done.

Как править абзац:

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}} напишите, что изменили. Пустой комментарий не оставляйте.

4. Commit (зелёная кнопка), затем Push (красная).
5. Подождите несколько минут. Сборка сайта — это не мгновенное сохранение: GitLab забирает статью и заново собирает внутренний сайт. Если в статье нет ошибок из части D, она появится по адресу из начала этой инструкции. Подробнее в C4.

Если push отклонён и вылезло окно как на рисунке:

нажмите Pull (оранжевая кнопка), дождитесь окончания и снова Push. Если Git пишет про конфликт — не выбирайте файлы наугад, позовите админа.

C3. Запасной вариант (PowerShell)

Если кнопки Obsidian Git не работают — позовите админа или в 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)
 для картинки продукта	![[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 или другой файл через обычную ссылку

Нельзя:

[скачать](./manual.pdf)

Нужно (как в B5):

![[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.