Как сделать многостраничную документацию внутри одного HTML-файла

Один файл не обязан быть одной длинной страницей

Объединение руководства в один HTML часто понимают как размещение всех глав на одной очень длинной странице. По мере роста документа ее становится трудно просматривать. Оглавление разрастается, а читателю сложнее понять, в какой части руководства он находится.

Более удобная модель разделяет содержимое на логические страницы, но хранит их данные и просмотрщик в одном физическом файле. Читатель переходит между быстрым стартом, настройкой, руководствами, API Reference и устранением неполадок как на небольшом сайте. Папка со сгенерированными страницами при этом не нужна.

Спроектируйте дерево вокруг задач читателя

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

Давайте страницам короткие и различающиеся названия. Используйте вложенность только для настоящей связи родителя и дочерних страниц. Два или три полезных уровня обычно удобнее глубокого дерева. Внутри страниц последовательно применяйте заголовки h2 и h3, чтобы оглавление показывало детали текущего материала.

Обзор
Начало работы
  Установка
  Первый проект
Руководства
  Настройка
  Развертывание
Справочник
Устранение неполадок

Используйте стабильные маршруты и внутренние ссылки

Страницы одного файла можно адресовать через фрагменты URL, также называемые hash-маршрутами. Адрес вида #/guides/deployment сообщает встроенному просмотрщику, какую страницу показать. Дополнительный якорь может указывать на заголовок этой страницы.

Назначайте стабильные и понятные идентификаторы, а не создавайте все маршруты из заголовков, которые могут измениться или быть переведены. После переноса или переименования страниц проверяйте входящие ссылки. One File Docs проверяет внутренние ссылки и разрешает конфликты между маршрутами страниц и заголовков, но итоговый экспорт все равно нужно протестировать глазами читателя.

Добавьте навигацию, подходящую для большого документа

Основное дерево отвечает на вопрос «где я нахожусь в руководстве?». Оглавление страницы показывает, что находится на ней. Поиск помогает найти место, где упоминался термин. Большому документу полезны все три механизма, но они не должны занимать одно и то же пространство.

Оставляйте активную страницу видимой в дереве, избегайте почти одинаковых общих названий и исключайте из экспорта внутренние или незавершенные разделы. Для динамических разделов можно выбрать размещение страниц в шапке или оглавлении, а заголовков — в общем дереве либо отдельной панели «На этой странице».

Экспортируйте и проверьте результат

One File Docs включает структуру страниц, содержимое, навигацию, поиск, код просмотрщика, стили и импортированные изображения в один HTML-файл. Его можно открыть локально, приложить к выпуску или разместить на статическом хостинге без сборки отдельного сайта.

После экспорта откройте несколько глубоких ссылок, воспользуйтесь кнопками браузера «Назад» и «Вперед», найдите слова с разных страниц и проверьте якоря заголовков. Если документ должен работать без сети, используйте полный чеклист из руководства по автономной HTML-документации.