Начало работы с VitePress

Пробуем онлайн

Вы можете опробовать 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

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

bun

$ bunx 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 как пир-зависимость

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

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

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

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

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

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

TIP

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

Файл конфигурации

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

с самых основных опций, таких как название и описание сайта:

// .vitepress/config.js
export default {
  // опции на уровне сайта
  title: 'VitePress',
  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 запустит локальный сервер разработки с мгновенными горячими обновлениями. Запустите его с помощью следующей команды:

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 exec vitepress dev docs

bun

$ bunx vitepress dev docs

Больше информации о командной строке документировано в Справочнике по CLI.

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

Что дальше?

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

• Чтобы узнать больше о том, что вы можете делать на странице, например, писать контент markdown или использовать компоненты Vue, обратитесь к разделу "Написание". Хорошей отправной точкой будет изучение Расширений Markdown.

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

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

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