Навигация

В mxLocDoc две независимые навигации:

• левое меню — список всех документов, задаётся манифест-файлом (или строится автоматически);
• навигация по странице — правый список «На этой странице», собирается из заголовков открытого документа.

Левое меню

Откуда берётся

По умолчанию читается манифест _sidebar.json (имя задаётся настройкой mxlocdoc.nav_file). Если его нет — проверяется mxlocdoc.json. Если манифеста нет совсем, mxLocDoc строит дерево автоматически по Markdown-файлам (fallback, см. ниже).

Пример манифеста

{
  "title": "Project Docs",
  "items": [
    {"title": "Обзор", "path": "README.md"},
    {"title": "Руководство", "path": "guide/README.md", "items": [
      {"title": "Установка", "path": "guide/setup.md"},
      {"title": "Настройки", "path": "guide/configuration.md"}
    ]}
  ]
}

Верхний уровень: title — заголовок всего меню, items — массив пунктов.

Поля пункта

• title — подпись пункта в меню. Если не указан, берётся title из front matter документа, а если нет и его — имя файла.
• path — путь к Markdown-файлу относительно корня документации (или языкового подкорня, если включены языки). Пункт с path — кликабельная страница. README.md в папке принято использовать как индекс раздела.
• items — вложенные пункты. Так строится дерево любой глубины.
• hidden — true, чтобы скрыть пункт (и всю его ветку) из меню.

Раздел или страница

• Пункт с path — страница: клик открывает документ.
• Пункт без path, но с items — раздел: заголовок группы, клик по нему ничего не грузит. Чтобы раздел был кликабельным, дайте ему path (обычно на README.md раздела) и items для вложенных страниц.

Front matter документа

Каждый документ может нести front matter — шапку в начале файла между строками ---:

---
title: Установка
order: 1
hidden: false
---

• title — подпись, если она не задана в манифесте;
• order — используется для сортировки в fallback-режиме (без манифеста);
• hidden: true — скрывает документ и из манифест-меню, и из fallback.

Fallback без манифеста

Если манифест не найден, mxLocDoc строит меню по самим файлам: папки становятся разделами, README.md внутри папки — её индексом, порядок — по order из front matter. Скрытые документы пропускаются. Все пути проходят ту же проверку безопасного filesystem-слоя, что и обычные запросы документов, — выйти за пределы корня документации нельзя.

Навигация по странице

Правый список «На этой странице» строится автоматически из заголовков открытого документа — уровней #, ##, ### (h1–h3).

• Вложенность в списке повторяет уровень заголовка: ## вкладывается в #, ### — в ##.
• Клик по пункту плавно прокручивает документ к нужному заголовку.
• Если заголовков h1–h3 нет, список скрывается. Заголовки #### и глубже в это оглавление не попадают.