Docus: документация на Nuxt и Markdown — примеры и настройка

Хорошая документация помогает человеку сделать конкретную работу: запустить проект, найти настройку, исправить ошибку и продолжить без переписки с автором. Docus собирает такой сайт из Markdown-файлов: с навигацией, поиском, оглавлением и оформлением на основе Nuxt UI.

На этой странице — бесплатная мастерская без регистрации и шесть практических примеров. Посмотрите, как выглядит настоящая документация на Docus, сравните светлую и темную темы, изучите Markdown и MDC, затем скачайте учебный проект для собственного сайта.

В предпросмотре работает настоящий Docus 5.14.0 на Nuxt 4.5.2. Учебные тексты, сценарии и внешняя панель подготовлены для этой статьи. Поиск, переходы между страницами и компоненты документации относятся к Docus; мастерская помогает рассмотреть их и забрать пример. ИИ-ассистент в демонстрации отключен.

Для чего подойдет Docus

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

Актуальный Docus — слой для Nuxt 4 с Nuxt Content, Nuxt UI 4 и Tailwind CSS 4. Обычный Markdown отвечает за текст; расширение MDC позволяет включать Vue-компоненты прямо в документ. Исходный проект опубликован под MIT. Состав и лицензию можно проверить в официальном репозитории.

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

Пример 1. Создать проект документации

Для запуска нужен Node.js версии, совместимой с выбранным Nuxt, и пакетный менеджер. Для скачанного учебного проекта используйте Node.js 24. Выполните команды в папке, где будут храниться проекты:

npx create-docus project-handbook
cd project-handbook
npm run dev

Откройте локальный адрес, который напечатает сервер разработки; обычно это http://localhost:3000. Первый запуск устанавливает зависимости. Если команда сообщает об отсутствии пакетов, выполните npm install в папке проекта. Этот способ создания описан в инструкции Docus.

В учебном проекте версии закреплены в package.json и файле блокировки. Для повторяемой установки используйте npm ci. Команда создания выше получает актуальный шаблон, поэтому его зависимости в будущем могут отличаться от примера статьи.

Создайте или дополните nuxt.config.ts. Здесь оставляем основу для обычной документации без ИИ:

export default defineNuxtConfig({
  extends: ['docus'],
  site: {
    name: 'Руководство проекта',
    url: 'https://docs.example.com'
  },
  docus: {
    assistant: { enabled: false }
  },
  mcp: { enabled: false }
})

Замените адрес на свой перед публикацией. Файл Nuxt-конфигурации нужен и для применения собственных настроек приложения. Отключение MCP здесь соответствует учебной статической сборке; при отдельном серверном развертывании его можно настроить по официальному руководству MCP.

Пример 2. Страница с заголовком и SEO

Добавьте файл content/1.guide/1.quick-start.md. Блок между первыми двумя строками --- задает метаданные, а ниже находится текст документа. В этом примере разделяем видимый заголовок и заголовок для поиска:

---
title: Быстрый старт
description: Создайте первый проект и проверьте результат.
seo:
  title: Первый проект — руководство по запуску
  description: Пошаговый запуск проекта и проверка результата в браузере.
---

## Что понадобится

- Установленный Node.js.
- Папка для проекта.
- Несколько минут на первую сборку.

## Проверка результата

Откройте локальную страницу. Если видны заголовок и навигация,
можно переходить к настройке оформления.

[Следующий шаг: оформление](/guide/appearance)

Числовые префиксы помогают расположить материалы по порядку. Для ссылок используйте адрес страницы, без цифр имени файла и расширения .md. Правила содержимого и метаданных описаны в разделе Edition; порядок файлов можно посмотреть в официальном шаблоне.

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

Пример 3. Содержание и понятная навигация

Для небольшого руководства достаточно одной папки. Главная страница находится отдельно, изображения и другие готовые файлы — в public:

project-handbook/
├── content/
│   ├── index.md
│   └── 1.guide/
│       ├── .navigation.yml
│       ├── 1.quick-start.md
│       ├── 2.appearance.md
│       └── 3.troubleshooting.md
├── public/
│   └── images/
│       └── setup.webp
├── app/
│   └── app.config.ts
└── nuxt.config.ts

В .navigation.yml запишите две строки: title: Руководство и icon: i-lucide-book-open. Они задают название группы и значок. Файл 2.appearance.md из этого дерева будет доступен по /guide/appearance.

Можно использовать отдельную папку content/docs, если документация должна жить под /docs вместе с другими страницами. Docus учитывает структуру содержимого при создании маршрутов. Варианты описаны в схеме проекта.

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

Пример 4. Цвет, язык интерфейса и поиск

В app/app.config.ts нашего Nuxt 4 проекта зададим название, цветовой акцент и русские подписи. Светлую и темную темы оставляем на выбор посетителя:

export default defineAppConfig({
  header: { title: 'Руководство проекта' },
  ui: {
    colors: { primary: 'teal', neutral: 'slate' }
  },
  docus: { locale: 'ru' },
  toc: { title: 'На этой странице' },
  github: false,
  search: { fts: false }
})

Параметры цветов основаны на системе Nuxt UI; ее настройка описана в руководстве Theme. Если нужны собственные CSS-переменные, используйте app/app.css. Docus подключает его сам; повторно импортировать Tailwind в этом файле не требуется.

По умолчанию поиск выполняет клиентская фильтрация Fuse.js. Дополнительный режим search.fts: true использует индекс SQLite FTS5 в браузере через WASM. Для небольшого учебного проекта оставлен обычный поиск. Различия режимов и настройки тем разобраны в Configuration.

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

Пример 5. Инструкция с шагами и заметкой

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

::note
После изменения документации нужно пересобрать опубликованный сайт.
::

::steps{level="3"}
### Подготовьте материал

Добавьте заголовок, описание и одну проверяемую инструкцию.

### Откройте предпросмотр

Проверьте ссылки, таблицы и длинные строки кода.

### Опубликуйте обновление

Соберите сайт и перенесите готовые файлы на хостинг.
::

::card{title="Если запуск не удался" to="/guide/troubleshooting"}
Откройте список частых ошибок и сравните сообщение с вашим.
::

Названия note, steps и card относятся к компонентам Docus/Nuxt UI. В обычном Markdown-просмотрщике такой блок может остаться текстом. Для вложенных компонентов используется больше двоеточий; свойства можно задавать внутри фигурных скобок или отдельным YAML-блоком. Синтаксис проверяйте по справочнику Markdown Components.

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

Пример 6. Русская и английская документация

Для нового многоязычного проекта можно сразу выбрать шаблон командой npx create-docus project-handbook -t i18n. В существующем проекте выполните npm install @nuxtjs/i18n, затем дополните конфигурацию:

export default defineNuxtConfig({
  extends: ['docus'],
  modules: ['@nuxtjs/i18n'],
  i18n: {
    defaultLocale: 'ru',
    locales: [
      { code: 'ru', name: 'Русский', language: 'ru-RU' },
      { code: 'en', name: 'English', language: 'en-US' }
    ],
    detectBrowserLanguage: false
  },
  docus: { assistant: { enabled: false } },
  mcp: { enabled: false },
  hooks: {
    'pages:resolved'(pages) {
      const normalize = (items: typeof pages) => {
        for (const page of items) {
          page.path = page.path.replace(/\/:lang\?(?=\/|$)/, '') || '/'
          if (page.children) normalize(page.children)
        }
      }
      normalize(pages)
    }
  }
})

В зафиксированной учебной сборке блок hooks устраняет конфликт языкового сегмента с префиксами i18n. Он нужен для сочетания Docus 5.14.0, Nuxt 4.5.2 и @nuxtjs/i18n 10.6.0; полный проверенный файл включен в архив. При переходе на другие версии сначала проверьте прямые ссылки на вложенные страницы.

Разместите переводы в параллельных папках content/ru и content/en. Например, русский файл content/ru/1.guide/1.quick-start.md и английский content/en/1.guide/1.quick-start.md должны описывать один и тот же шаг. Docus использует режим prefix: маршруты получат /ru и /en, включая основной язык.

i18n организует языки и переходы, но не переводит содержание автоматически. Тексты, примеры и подписи внутри собственных материалов готовит автор. Следите, чтобы структура двух языков совпадала и основной язык действительно существовал в content. Подробности — в руководстве Internationalization.

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

Скачанный проект предназначен для продолжения разработки: в нем есть исходные Markdown-файлы, настройки и инструкции запуска. Для обычной публичной документации можно сделать статическую сборку командой npx nuxt generate и разместить содержимое .output/public на подходящем хостинге.

После выгрузки откройте прямую ссылку на внутреннюю страницу и обновите ее. Проверьте изображения, поиск, переключение языка и ссылки на телефоне. При размещении в подпапке настройте app.baseURL до сборки. Серверные обработчики, авторизация и другие функции с исполнением на сервере требуют отдельного развертывания Nuxt/Nitro; статическая папка их не заменяет.

Перед публикацией собственного проекта: учебный архив запрещает индексацию через noindex, nofollow, а sitemap, robots и генерация OG-изображений отключены. Это настройки демонстрации. Для рабочего сайта уберите учебный запрет индексации, настройте свой адрес и включите нужные SEO-модули. Порядок изменений указан в инструкции архива; сама статья на этом сайте доступна для индексации.

Где здесь ИИ и что означает «бесплатно»

Базовый Docus открыт, а наша мастерская доступна бесплатно без регистрации. Хостинг, домен и выбранные внешние услуги оплачиваются отдельно по условиям поставщиков.

ИИ-ассистент — дополнительная возможность Docus. В стандартном варианте он использует Vercel AI Gateway и требует настройки доступа; другой провайдер подключается через собственный серверный обработчик. Расходы зависят от провайдера и использования. Ключи хранятся в серверном окружении, а не в Markdown, публичном JavaScript или скачиваемом архиве. Подключение описано в руководстве Assistant.

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

Еще примеры для вашего проекта

Если в документации нужны обучающие ролики, посмотрите мастерскую Video.js. Для настройки React-интерфейсов пригодится площадка shadcn Studio, а отдельную HTML-страницу можно собрать в конструкторе Bootstrap 5.