# Первые шаги {#getting-started} ## Попробуйте онлайн {#try-it-online} Вы можете попробовать VitePress прямо в браузере на [StackBlitz](https://vitepress.new). ## Установка {#installation} ### Требования {#prerequisites} - [Node.js](https://nodejs.org/) версии 18 или выше. - Терминал для доступа к VitePress через интерфейс командной строки (CLI). - Текстовый редактор с поддержкой синтаксиса [Markdown](https://ru.wikipedia.org/wiki/Markdown). - Рекомендуется использовать [VSCode](https://code.visualstudio.com/), а также [официальное расширение Vue](https://marketplace.visualstudio.com/items?itemName=Vue.volar). VitePress можно использовать самостоятельно или установить в существующий проект. В обоих случаях вы можете установить его с помощью: ::: code-group ```sh [npm] $ npm add -D vitepress ``` ```sh [pnpm] $ pnpm add -D vitepress ``` ```sh [yarn] $ yarn add -D vitepress ``` ```sh [yarn (pnp)] $ yarn add -D vitepress vue ``` ```sh [bun] $ bun add -D vitepress ``` ::: ::: details Получаете предупреждения об отсутствующих зависимостях? Если вы используете PNPM, вы заметите предупреждение об отсутствующем пакете `@docsearch/js`. Это не мешает работе VitePress. Если вы хотите подавить это предупреждение, добавьте следующее в ваш `package.json`: ```json "pnpm": { "peerDependencyRules": { "ignoreMissing": [ "@algolia/client-search", "search-insights" ] } } ``` ::: ::: tip ПРИМЕЧАНИЕ VitePress — это пакет, предназначенный только для ESM. Не используйте `require()` для импорта, и убедитесь, что ближайший `package.json` содержит `"type": "module"`, или измените расширение соответствующих файлов, например, `.vitepress/config.js` на `.mjs`/`.mts`. Более подробную информацию см. в [Руководстве по устранению неполадок Vite](https://vitejs.dev/guide/troubleshooting.html#this-package-is-esm-only). Кроме того, внутри асинхронных контекстов CJS можно использовать `await import('vitepress')` вместо этого. ::: ### Мастер настройки {#setup-wizard} VitePress поставляется с мастером настройки командной строки, который поможет вам создать базовый проект. После установки запустите мастер, запустив его: ::: code-group ```sh [npm] $ npx vitepress init ``` ```sh [pnpm] $ pnpm vitepress init ``` ```sh [yarn] $ yarn vitepress init ``` ```sh [bun] $ bun vitepress init ``` ::: Вас встретят несколькими простыми вопросами: <<< @/snippets/init.ansi ::: tip Vue как зависимость Если вы собираетесь выполнять кастомизацию с использованием компонентов или API Vue, вам также следует явно установить `vue` в качестве зависимости. ::: ## Структура файлов {#file-structure} Если вы создаете отдельный сайт VitePress, вы можете разместить его в текущей директории (`./`). Однако если вы устанавливаете VitePress в существующий проект вместе с другим исходным кодом, рекомендуется поместить сайт во вложенную директорию (например, `./docs`), чтобы он был отделён от остальной части проекта. Если предположить, что вы решили разместить проект VitePress в `./docs`, то сгенерированная структура файлов должна выглядеть следующим образом: ``` . ├─ docs │ ├─ .vitepress │ │ └─ config.js │ ├─ api-examples.md │ ├─ markdown-examples.md │ └─ index.md └─ package.json ``` Директория `docs` считается **корнем проекта** сайта VitePress. Директория `.vitepress` — это зарезервированное место для конфигурационного файла VitePress, кэша dev-сервера, результатов сборки и дополнительного кода настройки темы. ::: tip СОВЕТ По умолчанию VitePress хранит кэш своего dev-сервера в файле `.vitepress/cache`, а выходные данные сборки — в файле `.vitepress/dist`. Если вы используете Git, вам следует добавить их в файл `.gitignore`. Эти места также могут быть [сконфигурированы](../reference/site-config#outdir). ::: ### Конфигурационный файл {#the-config-file} Файл конфигурации (`.vitepress/config.js`) позволяет настраивать различные аспекты сайта VitePress, самыми основными из которых являются название и описание сайта: ```js // .vitepress/config.js export default { // параметры сайта title: 'Заголовок сайта', description: 'Описание сайта.', themeConfig: { // параметры темы } } ``` Вы также можете настроить поведение темы с помощью опции `themeConfig`. Загляните в главу [Настройка сайта](../reference/site-config) для получения подробной информации обо всех параметрах конфигурации. ### Исходные файлы {#source-files} Файлы Markdown за пределами директории `.vitepress` считаются **исходными файлами**. VitePress использует **маршрутизацию на основе файлов**: Каждый файл `.md` компилируется в соответствующий файл `.html` с тем же путем. Например, `index.md` будет скомпилирован в `index.html`, и его можно будет посетить по корневому пути `/` результирующего сайта VitePress. VitePress также предоставляет возможность генерировать чистые URL-адреса, переписывать пути и динамически генерировать страницы. Всё это будет рассмотрено в [Руководстве по маршрутизации](./routing). ## Скрипты запуска {#up-and-running} Мастер настройки также должен был внедрить следующие скрипты npm в ваш `package.json`, если вы разрешили ему это сделать в процессе установки: ```json { ... "scripts": { "docs:dev": "vitepress dev docs", "docs:build": "vitepress build docs", "docs:preview": "vitepress preview docs" }, ... } ``` Скрипт `docs:dev` запустит локальный dev-сервер с мгновенными горячими обновлениями. Запустите его с помощью следующей команды: ::: code-group ```sh [npm] $ npm run docs:dev ``` ```sh [pnpm] $ pnpm run docs:dev ``` ```sh [yarn] $ yarn docs:dev ``` ```sh [bun] $ bun run docs:dev ``` ::: Вместо npm-скриптов вы также можете вызывать VitePress напрямую с помощью: ::: code-group ```sh [npm] $ npx vitepress dev docs ``` ```sh [pnpm] $ pnpm vitepress dev docs ``` ```sh [yarn] $ yarn vitepress dev docs ``` ```sh [bun] $ bun vitepress dev docs ``` ::: Более подробная информация об использовании командной строки описана в главе [Командная строка](../reference/cli). Dev-сервер должен быть запущен по адресу `http://localhost:5173`. Перейдите по URL-адресу в браузере, чтобы увидеть новый сайт в действии! ## Что дальше? {#what-s-next} - Чтобы лучше понять, как Markdown-файлы сопоставляются с генерируемым HTML, перейдите к [Руководству по маршрутизации](./routing). - Чтобы узнать больше о том, что вы можете делать на странице, например, писать содержимое в формате Markdown или использовать компоненты Vue, обратитесь к разделу «Написание». Начать стоит с изучения главы [Расширения Markdown](./markdown). - Чтобы изучить возможности, предоставляемые темой документации по умолчанию, ознакомьтесь с главой [Настройка темы по умолчанию](../reference/default-theme-config). - Если вы хотите ещё больше изменить внешний вид своего сайта, изучите главы [Расширение темы по умолчанию](./extending-default-theme) или [Пользовательская тема](./custom-theme). - Как только ваш сайт документации обретёт форму, обязательно прочитайте [Руководство по развёртыванию](./deploy).