Формирование и актуализация Markdown-исходников документации: различия между версиями

Текущая версия от 07:36, 13 мая 2026

Формирование структуры и содержимого документации осуществляется следующим образом:

создание (редактирование) файлов расширения Markdown, каждый из которых является отдельным документом и соответствует определённой главе или подразделу;
распределение .md файлов в файловой структуре согласно иерархии.

Оглавление, описанное в SUMMARY.md состоит из элементов, каждый из которых определяет то, какой будет структура оглавления и каким будет контент каждой главы в итоговом документе.

Пример оглавления в SUMMARY.md может выглядеть следующим образом:

[Общая информация]()

# Глава 1
- [Назначение и общие сведения]()
  - [Общие приёмы работы]()
  - [Общий порядок работы]()

---

# Глава 2
- [Описание работы и синтаксиса скриптов]()
  - [Типы данных](Описание_работы_и_синтаксиса_скриптов/1.Типы_данных/1.Типы_данных.md)
  - [Операторы](Описание_работы_и_синтаксиса_скриптов/2.Операторы/2.Операторы.md)
  - [Переменные](Описание_работы_и_синтаксиса_скриптов/3.Переменные/3.Переменные.md)
  - [Функции и методы](Описание_работы_и_синтаксиса_скриптов/4.Функции_и_методы/4.Функции_и_методы.md)
  - [Синтаксические конструкции](Описание_работы_и_синтаксиса_скриптов/5.Синтаксические_конструкции/5.Синтаксические_конструкциии.md)
  - [Примеры и комментарии](Описание_работы_и_синтаксиса_скриптов/6.Примеры/6.Примеры.md)

[Инструкция mdBook](readme.md)

Страница с документацией с данным оглавлением будет иметь следующий вид:

Ссылки

Ссылки - являются основной структурной единицей оглавления и состоят из:

названия главы (подраздела) - в квадратных скобках,
пути к .md файлу, соответствующему содержимому раздела (указывается относительно корневой папки проекта со всей документацией) - в круглых скобках.

Важно: для корректного отображения страницы при создании ссылок в пути к файлу необходимо использовать прямой слэш /.

Элементы

Элементы, которые используются при создании оглавлений:

Ненумерованные главы,
Ненумерованный заголовок первого уровня,
Нумерованный заголовок,
Глава-черновик,
Разделитель.

Ненумерованные главы

В SUMMARY.md таким главам соответствует ссылка без знака - и табуляции.

Префиксная глава - добавляется перед основными пронумерованными главами.

Такие главы не будут пронумерованы. Это полезно для предисловий, вступлений и т. д.

На такие главы существуют ограничения:

префиксные главы не могут быть вложенными;
все они должны быть на корневом уровне.
не получится добавить префиксные главы после добавления пронумерованных глав.

Суффиксная глава - как и главы-префиксы, главы-суффиксы не нумеруются, но следуют после пронумерованных глав.

Ненумерованный заголовок первого уровня

В SUMMARY.md таким заголовкам соответствует текст с одним знаком # в начале.

Заголовки уровня 1 можно использовать в качестве заголовка для следующих пронумерованных глав.

Это можно использовать для логического разделения различных разделов документа.

Заголовок отображается как некликабельный текст.

Заголовки необязательны, а пронумерованные главы можно разбить на столько частей, сколько необходимо.

Заголовки частей должны быть заголовками уровня h1 (один #), другие уровни заголовков игнорируются.

Нумерованный заголовок

В SUMMARY.md таким главам соответствует ссылка со знаком -.

Нумерованные главы описывают основное содержание документа и могут быть вложенными, что позволяет создать необходимую иерархию (главы, подглавы и т. д.).

Чтобы сделать нумерованную главу вложенной, к ссылке в начале добавляется табуляция

Глава-черновик

В SUMMARY.md таким главам соответствует ссылка с пустым путём к файлу с описанием.

Главы-черновики - это главы без файла и, следовательно, контента.

Обычно используются разметки структуры документа, когда отсутствует содержание глав.

Такие главы отображаются как неактивные ссылки в оглавлении.

Главы-черновики пишутся как обычные главы, но без записи пути к файлу

Разделитель

Разделитель - это строка, содержащая три и более тире: ---.

Разделитель добавляет полосу, отделяющую одну часть оглавления от другой.

Файловая структура при документировании

Для удобства разработки документации, формирования понятной файловой структуры и корректного отображения содержимого генерируемой веб-страницы необходимо следовать следующим правилам:

файлы, описывающие каждый раздел необходимо располагать согласно структуре оглавления;
для каждого раздела создаётся директория;
для корневых разделов директории с описанием находятся в корне проекта src;
если раздел содержит подразделы, создаются поддиректории внутри раздела;
в директории каждого раздела находятся файл с расширением .md, с документацией соответствующей главы;
названия всех папок и файлов должны быть без пробелов;
если раздел или подраздел содержит изображения, в соответствующей директории создаётся папка assets, в которой размещаются файлы изображений;
изображения именуются как asset_1, asset_2, ... и т.д. в том порядке, в котором они расположены в разделе документации, к которому относятся.

Ниже приведён пример оглавления в SUMMARY.md и соответствующая ему файловая структура.

[Общая информация]()

# Глава 1
- [Назначение и общие сведения]()
  - [Общие приёмы работы]()
  - [Общий порядок работы]()

---

# Глава 2
- [Описание работы и синтаксиса скриптов](Описание_работы_и_синтаксиса_скриптов/Описание_работы_и_синтаксиса_скриптов.md)
  - [Типы данных](Описание_работы_и_синтаксиса_скриптов/1.Типы_данных/1.Типы_данных.md)
  - [Операторы](Описание_работы_и_синтаксиса_скриптов/2.Операторы/2.Операторы.md)
  - [Переменные](Описание_работы_и_синтаксиса_скриптов/3.Переменные/3.Переменные.md)
  - [Функции и методы](Описание_работы_и_синтаксиса_скриптов/4.Функции_и_методы/4.Функции_и_методы.md)
  - [Синтаксические конструкции](Описание_работы_и_синтаксиса_скриптов/5.Синтаксические_конструкции/5.Синтаксические_конструкциии.md)
  - [Примеры и комментарии](Описание_работы_и_синтаксиса_скриптов/6.Примеры/6.Примеры.md)

[Инструкция по документированию](readme.md)

Файловая структура:

Работа с Markdown файлами

При написании документации в markdown редактировать содержимое можно либо вручную, либо через графический интерфейс VSCode

Для "ручного" редактирования - инструкция по использованию markdown: https://gist.github.com/Jekins/2bf2d0638163f1294637

Для редактирования через интерфейс VSCode можно использовать как стандартный функционал, так и расширения

Использование стандартного функционала:

Выделить текст и нажать по нему ПКМ Нажать "Рефакторинг" Выбрать необходимую функцию из появившегося списка или "Дополнительно" Через расширение EasyMarkdown:

установить расширение выделить редактируемый текст нажать на одну из кнопок редактирования текста в правом верхнем углу окна просмотра документа

@@ Строка 59: / Строка 59: @@
 *Глава-черновик,
 *Разделитель.
+----
 ===Ненумерованные главы===
@@ Строка 73: / Строка 75: @@
 '''Суффиксная глава''' - как и главы-префиксы, главы-суффиксы не нумеруются, но следуют после пронумерованных глав.
+----
 ===Ненумерованный заголовок первого уровня===
@@ Строка 86: / Строка 90: @@
 Заголовки частей должны быть заголовками уровня <code>h1</code> (один <code>#</code>), другие уровни заголовков игнорируются.
+----
 ===Нумерованный заголовок===
@@ Строка 94: / Строка 100: @@
 Чтобы сделать нумерованную главу вложенной, к ссылке в начале добавляется табуляция
+----
 ===Глава-черновик===
 В <code>SUMMARY.md</code> таким главам соответствует ссылка с пустым путём к файлу с описанием.
@@ Строка 105: / Строка 114: @@
 Главы-черновики пишутся как обычные главы, но без записи пути к файлу
+----
 ===Разделитель===
@@ Строка 113: / Строка 124: @@
 ==Файловая структура при документировании==
 Для удобства разработки документации, формирования понятной файловой структуры и корректного отображения содержимого генерируемой веб-страницы необходимо следовать следующим правилам:
+*файлы, описывающие каждый раздел необходимо располагать согласно структуре оглавления;
+*для каждого раздела создаётся директория;
+*для корневых разделов директории с описанием находятся в корне проекта <code>src</code>;
+*если раздел содержит подразделы, создаются поддиректории внутри раздела;
+*в директории каждого раздела находятся файл с расширением <code>.md</code>, с документацией соответствующей главы;
+*названия всех папок и файлов должны быть без пробелов;
+*если раздел или подраздел содержит изображения, в соответствующей директории создаётся папка <code>assets</code>, в которой размещаются файлы изображений;
+*изображения именуются как <code>asset_1</code>, <code>asset_2</code>, ... и т.д. в том порядке, в котором они расположены в разделе документации, к которому относятся.
-Файлы, описывающие каждый раздел необходимо располагать согласно структуре оглавления
+Ниже приведён ''пример оглавления'' в <code>SUMMARY.md</code> и соответствующая ему ''файловая структура''.
-Для каждого раздела создаётся директория; для корневых разделов директории с описанием находятся в корне проекта src
-Если раздел содержит подразделы, создаются поддиректории внутри раздела
-В директории каждого раздела находятся файл с расширением .md, с документацией соответствующей главы
-Названия всех папок и файлов должны быть без пробелов
-Если раздел или подраздел содержит изображения, в соответствующей директории создаётся папка assets, в которой размещаются файлы изображений
-Изображения именуются как asset_1, asset_2, ... и т.д. в том порядке, в котором они расположены в разделе документации, к которому относятся
-Ниже приведён пример оглавления в SUMMARY.md и соответствующая ему файловая структура
-Оглавление в SUMMARY.md:
 <syntaxhighlight lang="markdown">