Как вести работу с документацией

Документация должна располагаться в папке assets

Заголовки нумеровать не надо, они автоматически сгенерируются на основе markdown разметки:

#   -> 1.
##  -> 1.1.
### -> 1.1.1.
##  -> 1.2.
### -> 1.2.1.
### -> 1.2.2.
...

При создании раздела, обязательно указывать meta-данные в начале .md файла:

---
title: 1. История изменений
section: 1
ignore-section-number: true
---

где:

• title - Заголовок раздела, который будет отображен в сайдбаре документации
• section - Номер раздела, этот номер будет учитываться при генерации номеров заголовков
• ignore-section-number - опциональное поле, можно либо вовсе не указывать его, либо указывать false. Если оно true - в этом файле не будет генерироваться нумерация, а просто файл будет использован как есть

При изменении порядка раздела нужно будет обновить meta-данные изменяемого раздела

Для обращения к папке с картинками писать путь @images/{имя подпапки?}/{имя картинки.формат}:

[Viking robot scheme](@images/bot-scheme.svg)
[Settings icon](@images/icons/settings.svg)

Для ссылки на документацию указывать имя файла в формате .md или .html:

1 вариант: 05-params-description.md     // <--- предпочтительнее использовать .md
2 вариант: 05-params-description.html  

если указать формат .md, тогда в среде разработки возможны подсказки ссылок по заголовкам

При генерации, для каждого заголовка будет сгенерирован свой slug и добавлен <Anchor :ids="[slug]" />

Если заголовок написан на русском - он будет переведен в транслит

Чтобы ссылаться на заголовки документации, можно:

Вариант 1

• Вызвать команду для генерации документации

yarn pre-process 
# Или npm run pre-process

• Перейти в сгенерированный файл в src/docs/нужный_документ.md
• Взять slug из якоря, который автосгенерирован для заголовка:

## <Anchor :ids="['kratkoe-opisanie-robota']" /> 2.1. Краткое описание робота

Вариант 2 - такой заголовок есть на сайте документации

• Перейти на сайт документации
• Нажать на # - для копирования ссылки
• Взять из ссылки только то что после #

https://fkviking.github.io/bot-doc/docs/02-faq.html#kratkoe-opisanie-robota

Вариант 3 - Обратиться к заголовку на русском языке

Так же существует возможность обратиться как к обычной ссылке в markdown

[двухфакторной аутентификации](getting-started.md#двухфакторная-аутентификация)

• После генерации, все ссылки так же будут переведены в транлит

Работа с Anchor для установки ссылок вручную

Предусмотрена возможность устанавливать ссылки в любое место документов, вручную. Для этого достаточно в исходном файле .md добавить <Anchor :ids="[имя вашей ссылки транслит или англ]" />

Как это работает

При добавлении <Anchor :ids="[whatever]" /> на него можно ссылаться из любого другого документа как document-name.md#whatever. Затем после генерации, на сайте документации, можно будет перейти в этом место, указав эту ссылку в адресной строке браузера

Важно

• Используйте в качестве имени ссылки(в ids) латинские символы(английский язык или транслит).
• При добавлении Anchor, после генерации, в этом месте на сайте документации будет отображаться кнопка # - для копирования ссылки
• Если хочется отключить это поведение - нужно добавить аттрибут hide

<Anchor hide :ids="[whatever]" />

• При этом, перейти на якорь все равно будет можно, просто скроется кнопка копирования

Локализация документации

В проект добавлена поддержка английской локализации. Порядок работы с документацией на английском языке такой же, как и для основной документации:

• Файлы для редактирования находятся в папке assets/en/
• Имена файлов должны совпадать с именами файлов на русском языке
• Содержание файлов должно соответствовать русской версии, иначе при авто-нумерации все сломается
• Если добавляется картинка, которая должна быть специально на английском языке, поместите её в assets/00-img/ и используйте ссылку в английском файле на неё, например: @images/my_image-en.png

Для запуска на локальной машине

To install packages

yarn install

To start test server

NODE_OPTIONS=--openssl-legacy-provider yarn run dev