Первые шаги

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

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

Установка

Требования

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

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

npm

$ npm add -D vitepress@next

pnpm

$ pnpm add -D vitepress@next

yarn

$ yarn add -D vitepress@next vue

bun

$ bun add -D vitepress@next

ПРИМЕЧАНИЕ

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 │ ◇ Where should VitePress look for your markdown files? │ ./docs │ ◇ Site title: │ My Awesome Project │ ◇ Site description: │ A VitePress Site │ ◇ Theme: │ Default Theme │ ◇ Use TypeScript for config and theme files? │ Yes │ ◇ Add VitePress npm scripts to package.json? │ Yes │ ◇ Add a prefix for VitePress npm scripts? │ Yes │ ◇ Prefix for VitePress npm scripts: │ docs │ └ Done! Now run pnpm run docs:dev and start writing.

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, если вы разрешили ему это сделать в процессе установки:

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.

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

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

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