Формирование и актуализация Markdown-исходников документации: различия между версиями
Sidminik (обсуждение | вклад) |
Sidminik (обсуждение | вклад) |
||
| Строка 59: | Строка 59: | ||
*Глава-черновик, | *Глава-черновик, | ||
*Разделитель. | *Разделитель. | ||
---- | |||
===Ненумерованные главы=== | ===Ненумерованные главы=== | ||
| Строка 73: | Строка 75: | ||
'''Суффиксная глава''' - как и главы-префиксы, главы-суффиксы не нумеруются, но следуют после пронумерованных глав. | '''Суффиксная глава''' - как и главы-префиксы, главы-суффиксы не нумеруются, но следуют после пронумерованных глав. | ||
---- | |||
===Ненумерованный заголовок первого уровня=== | ===Ненумерованный заголовок первого уровня=== | ||
| Строка 86: | Строка 90: | ||
Заголовки частей должны быть заголовками уровня <code>h1</code> (один <code>#</code>), другие уровни заголовков игнорируются. | Заголовки частей должны быть заголовками уровня <code>h1</code> (один <code>#</code>), другие уровни заголовков игнорируются. | ||
---- | |||
===Нумерованный заголовок=== | ===Нумерованный заголовок=== | ||
| Строка 94: | Строка 100: | ||
Чтобы сделать нумерованную главу вложенной, к ссылке в начале добавляется табуляция | Чтобы сделать нумерованную главу вложенной, к ссылке в начале добавляется табуляция | ||
---- | |||
===Глава-черновик=== | ===Глава-черновик=== | ||
В <code>SUMMARY.md</code> таким главам соответствует ссылка с пустым путём к файлу с описанием. | В <code>SUMMARY.md</code> таким главам соответствует ссылка с пустым путём к файлу с описанием. | ||
| Строка 105: | Строка 114: | ||
Главы-черновики пишутся как обычные главы, но без записи пути к файлу | Главы-черновики пишутся как обычные главы, но без записи пути к файлу | ||
---- | |||
===Разделитель=== | ===Разделитель=== | ||
Версия от 07:29, 13 мая 2026
Формирование структуры и содержимого документации осуществляется следующим образом:
- создание (редактирование) файлов расширения
Markdown, каждый из которых является отдельным документом и соответствует определённой главе или подразделу; - распределение
.mdфайлов в файловой структуре согласно иерархии.
Оглавление
Файл SUMMARY.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 и соответствующая ему файловая структура
Оглавление в 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:
установить расширение выделить редактируемый текст нажать на одну из кнопок редактирования текста в правом верхнем углу окна просмотра документа