Первые шаги

Попробуйте онлайн

Вы можете попробовать VitePress прямо в браузере на StackBlitz.

Установка

Требования

• Node.js версии 18 или выше.
• Терминал для доступа к VitePress через интерфейс командной строки (CLI).
• Текстовый редактор с поддержкой синтаксиса Markdown.
  • Рекомендуется использовать VSCode, а также официальное расширение Vue.

VitePress можно использовать самостоятельно или установить в существующий проект. В обоих случаях вы можете установить его с помощью:

npm

$ npm add -D vitepress

pnpm

$ pnpm add -D vitepress

yarn

$ yarn add -D vitepress

yarn (pnp)

$ yarn add -D vitepress vue

bun

$ bun add -D vitepress

Получаете предупреждения об отсутствующих зависимостях?

Если вы используете PNPM, вы заметите предупреждение об отсутствующем пакете @docsearch/js. Это не мешает работе VitePress. Если вы хотите подавить это предупреждение, добавьте следующее в ваш package.json:

"pnpm": {
  "peerDependencyRules": {
    "ignoreMissing": [
      "@algolia/client-search",
      "search-insights"
    ]
  }
}

ПРИМЕЧАНИЕ

VitePress — это пакет, предназначенный только для ESM. Не используйте require() для импорта, и убедитесь, что ближайший package.json содержит "type": "module", или измените расширение соответствующих файлов, например, .vitepress/config.js на .mjs/.mts. Более подробную информацию см. в Руководстве по устранению неполадок Vite. Кроме того, внутри асинхронных контекстов CJS можно использовать await import('vitepress') вместо этого.

Мастер настройки

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

npm

$ npx vitepress init

pnpm

$ pnpm vitepress init

yarn

$ yarn vitepress init

bun

$ bun vitepress init

Вас встретят несколькими простыми вопросами:

┌  Welcome to VitePress!
│
◇  Where should VitePress initialize the config?
│  ./docs
│
◇  Site title:
│  My Awesome Project
│
◇  Site description:
│  A VitePress Site
│
◆  Theme:
│  ● Default Theme (Out of the box, good-looking docs)
│  ○ Default Theme + Customization
│  ○ Custom Theme
└

Vue как зависимость

Если вы собираетесь выполнять кастомизацию с использованием компонентов или API Vue, вам также следует явно установить vue в качестве зависимости.

Структура файлов

Если вы создаете отдельный сайт VitePress, вы можете разместить его в текущей директории (./). Однако если вы устанавливаете VitePress в существующий проект вместе с другим исходным кодом, рекомендуется поместить сайт во вложенную директорию (например, ./docs), чтобы он был отделён от остальной части проекта.

Если предположить, что вы решили разместить проект VitePress в ./docs, то сгенерированная структура файлов должна выглядеть следующим образом:

.
├─ docs
│  ├─ .vitepress
│  │  └─ config.js
│  ├─ api-examples.md
│  ├─ markdown-examples.md
│  └─ index.md
└─ package.json

Директория docs считается корнем проекта сайта VitePress. Директория .vitepress — это зарезервированное место для конфигурационного файла VitePress, кэша dev-сервера, результатов сборки и дополнительного кода настройки темы.

СОВЕТ

По умолчанию VitePress хранит кэш своего dev-сервера в файле .vitepress/cache, а выходные данные сборки — в файле .vitepress/dist. Если вы используете Git, вам следует добавить их в файл .gitignore. Эти места также могут быть сконфигурированы.

Конфигурационный файл

Файл конфигурации (.vitepress/config.js) позволяет настраивать различные аспекты сайта VitePress, самыми основными из которых являются название и описание сайта:

// .vitepress/config.js
export default {
  // параметры сайта
  title: 'Заголовок сайта',
  description: 'Описание сайта.',

  themeConfig: {
    // параметры темы
  }
}

Вы также можете настроить поведение темы с помощью опции themeConfig. Загляните в главу Конфигурация сайта для получения подробной информации обо всех настраиваемых параметрах.

Исходные файлы

Файлы Markdown за пределами директории .vitepress считаются исходными файлами.

VitePress использует маршрутизацию на основе файлов: Каждый файл .md компилируется в соответствующий файл .html с тем же путём. Например, index.md будет скомпилирован в index.html, и его можно будет посетить по корневому пути / результирующего сайта VitePress.

VitePress также предоставляет возможность генерировать чистые URL-адреса, переписывать пути и динамически генерировать страницы. Всё это будет рассмотрено в Руководстве по маршрутизации.

Скрипты запуска

Мастер настройки также должен был внедрить следующие скрипты npm в ваш package.json, если вы разрешили ему это сделать в процессе установки:

{
  ...
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  },
  ...
}

Скрипт docs:dev запустит локальный dev-сервер с мгновенными горячими обновлениями. Выполните следующую команду:

npm

$ npm run docs:dev

pnpm

$ pnpm run docs:dev

yarn

$ yarn docs:dev

bun

$ bun run docs:dev

Вместо npm-скриптов вы также можете вызывать VitePress напрямую с помощью:

npm

$ npx vitepress dev docs

pnpm

$ pnpm vitepress dev docs

yarn

$ yarn vitepress dev docs

bun

$ bun vitepress dev docs

Более подробная информация об использовании командной строки описана в главе Командная строка.

Dev-сервер должен быть запущен по адресу http://localhost:5173. Перейдите по URL-адресу в браузере, чтобы увидеть новый сайт в действии!

Что дальше?

• Чтобы лучше понять, как Markdown-файлы сопоставляются с генерируемым HTML, перейдите к Руководству по маршрутизации.

• Чтобы узнать больше о том, что вы можете делать на странице, например, писать содержимое в формате Markdown или использовать компоненты Vue, обратитесь к разделу «Написание». Начать стоит с изучения главы Расширения Markdown.

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

• Если вы хотите ещё больше изменить внешний вид своего сайта, изучите главы Расширение темы по умолчанию или Пользовательская тема.

• Как только ваш сайт документации обретёт форму, обязательно прочитайте Руководство по развёртыванию.