Формирование и актуализация 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:

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

@@ Строка 1: / Строка 1: @@
 Формирование структуры и содержимого документации осуществляется следующим образом:
-*создание (редактирование) файлов расширения <code>Markdown</code>, являющихся отдельным документом с соответствующих определённой главе или подразделу;
+*создание (редактирование) файлов расширения <code>Markdown</code>, каждый из которых является отдельным документом и соответствует определённой главе или подразделу;
 *распределение <code>.md</code> файлов в файловой структуре согласно иерархии.
-==Создание оглавления==
+==Оглавление==
-'''Файл <code>SUMMARY.md</code>''' - необходим для формирования заголовков документации, их последовательности и иерархии.
+'''Файл <code>SUMMARY.md</code>''' (оглавление) - необходим для формирования заголовков документации, их последовательности и иерархии.
 Файл является неотъемлемой частью документации и должен находиться только в корне проекта.
@@ Строка 15: / Строка 15: @@
 Оглавление, описанное в <code>SUMMARY.md</code> состоит из элементов, каждый из которых определяет то, какой будет структура оглавления и каким будет контент каждой главы в итоговом документе.
-===Элементы оглавления в SUMMARY.md===
 Пример оглавления в <code>SUMMARY.md</code> может выглядеть следующим образом:
@@ Строка 34: / Строка 33: @@
    - [Переменные](Описание_работы_и_синтаксиса_скриптов/3.Переменные/3.Переменные.md)
    - [Функции и методы](Описание_работы_и_синтаксиса_скриптов/4.Функции_и_методы/4.Функции_и_методы.md)
-   - [Синтаксические конструкции](Описание_работы_и_синтаксиса_скриптов/5.Синтаксические_конструкции/5.Синтаксические_конструкциию.md)
+   - [Синтаксические конструкции](Описание_работы_и_синтаксиса_скриптов/5.Синтаксические_конструкции/5.Синтаксические_конструкциии.md)
    - [Примеры и комментарии](Описание_работы_и_синтаксиса_скриптов/6.Примеры/6.Примеры.md)
@@ Строка 43: / Строка 42: @@
 Страница с документацией с данным оглавлением будет иметь следующий вид:
+[[Файл:Help_18.png|center]]
-Основной структурной единицей оглавления являются ссылки
+==Ссылки==
-Ссылки состоят из:
+'''Ссылки''' - являются основной структурной единицей оглавления и состоят из:
+*''названия главы'' (подраздела) - в квадратных скобках,
+*''пути к <code>.md</code> файлу'', соответствующему содержимому раздела (указывается относительно корневой папки проекта со всей документацией) - в круглых скобках.
-названия главы (подраздела) - в квадратных скобках
+'''Важно:''' для корректного отображения страницы при создании ссылок в пути к файлу необходимо использовать прямой слэш <code>/</code>.
-пути к файлу, соответствующему содержимому раздела, формата markdown, относительно корневой папки проекта со всей документацией - в круглых скобках
-Важно: при при создании ссылок в пути к файлу необходимо использовать прямой слэш /. Это необходимо для корректного отображения страницы в документации.
-Элементы, которые используются при создании оглавлений:
+==Элементы==
-*Ненумерованные главы
-*Ненумерованный заголовок первого уровня
+'''Элементы''', которые используются при создании оглавлений:
-*Нумерованный заголовок
+*Ненумерованные главы,
-*Глава-черновик
+*Ненумерованный заголовок первого уровня,
-*Разделитель
+*Нумерованный заголовок,
+*Глава-черновик,
+*Разделитель.
+----
 ===Ненумерованные главы===
-В SUMMARY.md таким главам соответствует ссылка без знака - и табуляции
+В <code>SUMMARY.md</code> таким главам соответствует ссылка без знака <code>-</code> и табуляции.
 '''Префиксная глава''' - добавляется перед основными пронумерованными главами.
@@ Строка 72: / Строка 75: @@
 '''Суффиксная глава''' - как и главы-префиксы, главы-суффиксы не нумеруются, но следуют после пронумерованных глав.
+----
 ===Ненумерованный заголовок первого уровня===
-В SUMMARY.md таким заголовкам соответствует текст с одним знаком # в начале.
+В <code>SUMMARY.md</code> таким заголовкам соответствует текст с одним знаком <code>#</code> в начале.
-Заголовки уровня 1 можно использовать в качестве заголовка для следующих пронумерованных глав. Это можно использовать для логического разделения различных разделов документа.
+Заголовки уровня <code>1</code> можно использовать в качестве заголовка для следующих пронумерованных глав.
-Заголовок отображается как некликабельный текст. Заголовки необязательны, а пронумерованные главы можно разбить на столько частей, сколько необходимо.
-Заголовки частей должны быть заголовками h1 (один #), другие уровни заголовков игнорируются.
+Это можно использовать для логического разделения различных разделов документа.
+Заголовок отображается как некликабельный текст.
+Заголовки необязательны, а пронумерованные главы можно разбить на столько частей, сколько необходимо.
+Заголовки частей должны быть заголовками уровня <code>h1</code> (один <code>#</code>), другие уровни заголовков игнорируются.
+----
 ===Нумерованный заголовок===
-В SUMMARY.md таким главам соответствует ссылка со знаком -
+В <code>SUMMARY.md</code> таким главам соответствует ссылка со знаком <code>-</code>.
 Нумерованные главы описывают основное содержание документа и могут быть вложенными, что позволяет создать необходимую иерархию (главы, подглавы и т. д.).
 Чтобы сделать нумерованную главу вложенной, к ссылке в начале добавляется табуляция
+----
 ===Глава-черновик===
-В SUMMARY.md таким главам соответствует ссылка с пустым путём к файлу с описанием
-Главы-черновики - это главы без файла и, следовательно, контента. Обычно используются разметки структуры документа, когда отсутствует содержание глав. Такие главы отображаются как неактивные ссылки в оглавлении. Главы-черновики пишутся как обычные главы, но без записи пути к файлу
+В <code>SUMMARY.md</code> таким главам соответствует ссылка с пустым путём к файлу с описанием.
+'''Главы-черновики''' - это главы без файла и, следовательно, контента.
+Обычно используются разметки структуры документа, когда отсутствует содержание глав.
+Такие главы отображаются как неактивные ссылки в оглавлении.
+Главы-черновики пишутся как обычные главы, но без записи пути к файлу
+----
 ===Разделитель===
-Разделитель добавляет полосу, отделяющую одну часть оглавления от другой
-Разделитель - это строка, содержащая три и более тире: ---
+'''Разделитель''' - это строка, содержащая три и более тире: <code>---</code>.
+Разделитель добавляет полосу, отделяющую одну часть оглавления от другой.
 ==Файловая структура при документировании==
 Для удобства разработки документации, формирования понятной файловой структуры и корректного отображения содержимого генерируемой веб-страницы необходимо следовать следующим правилам:
+*файлы, описывающие каждый раздел необходимо располагать согласно структуре оглавления;
+*для каждого раздела создаётся директория;
+*для корневых разделов директории с описанием находятся в корне проекта <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">
 [Общая информация]()
 # Глава 1
 - [Назначение и общие сведения]()
-    - [Общие приёмы работы]()
+  - [Общие приёмы работы]()
-    - [Общий порядок работы]()
+  - [Общий порядок работы]()
 ---
@@ Строка 124: / Строка 153: @@
    - [Переменные](Описание_работы_и_синтаксиса_скриптов/3.Переменные/3.Переменные.md)
    - [Функции и методы](Описание_работы_и_синтаксиса_скриптов/4.Функции_и_методы/4.Функции_и_методы.md)
-   - [Синтаксические конструкции](Описание_работы_и_синтаксиса_скриптов/5.Синтаксические_конструкции/5.Синтаксические_конструкциию.md)
+   - [Синтаксические конструкции](Описание_работы_и_синтаксиса_скриптов/5.Синтаксические_конструкции/5.Синтаксические_конструкциии.md)
    - [Примеры и комментарии](Описание_работы_и_синтаксиса_скриптов/6.Примеры/6.Примеры.md)
 [Инструкция по документированию](readme.md)
+</syntaxhighlight>
 Файловая структура:
+[[Файл:Help_19.png|center]]
 ==Работа с Markdown файлами==