#Быстрый старт

#Подготовка окружения

Rspress поддерживает использование Node.js, Deno или Bun в качестве среды выполнения JavaScript.

Следуйте одному из следующих руководств по установке, чтобы настроить среду выполнения:

• Установка Node.js
• Установка Bun
• Установка Deno

#Онлайн-демонстрация

Вы можете попробовать Rspress прямо в CodeSandbox.

#Создание проекта Rspress

Рекомендуемый способ начать новый проект Rspress — использовать утилиту create-rspress:

npm create rspress@latest

yarn create rspress

pnpm create rspress@latest

bun create rspress@latest

deno init --npm rspress@latest

Утилита запросит название проекта или путь к нему, нужно ли настроить i18n, создавать ли папку theme для кастомизации, а также какие дополнительные инструменты или возможности добавить.

По умолчанию утилита инициализирует Git-репозиторий в созданном проекте. Передайте --no-git, чтобы пропустить инициализацию.

После создания проекта следуйте инструкциям, которые появятся в терминале:

cd rspress-project
git init # опционально
npm install
npm run dev

После запуска dev-сервер отобразит локальный URL-адрес. Откройте его в браузере, чтобы просмотреть сгенерированный сайт документации.

#Шаблоны

Rspress предоставляет следующие встроенные шаблоны:

#Дополнительные инструменты

При создании проекта вы можете выбрать дополнительные инструменты для линтинга или форматирования:

#Дополнительные навыки

Если вы планируете поддерживать сайт документации с помощью ИИ-агента, при создании проекта вы можете выбрать дополнительные навыки. CLI создаст директорию .agents/skills в вашем проекте и добавит туда выбранные навыки.

Для большинства сайтов документации мы рекомендуем выбрать:

• rspress-docs-generator: помогает ИИ-агентам создавать и сопровождать сайты документации на Rspress, особенно если в монорепозитории документация вынесена в отдельный проект на Rspress.
• rspress-best-practices: предоставляет ИИ-агентам рекомендации по структуре проекта Rspress, конфигурации, MDX, темам и развёртыванию.
• rspress-description-generator: помогает ИИ-агентам писать и поддерживать описания страниц для SEO, поиска и ИИ-читаемых результатов.

Если вы выберете шаблон basic-theme или i18n-theme, по умолчанию будет выбран следующий навык:

• rspress-custom-theme: позволяет вашему ИИ-агенту кастомизировать тему Rspress (CSS-переменные, слоты, переопределение компонентов темы).

Эти навыки не влияют на работу вашего сайта Rspress. Они предоставляют только локальные подсказки для ИИ-агентов при редактировании и поддержке проекта. Если вы не используете ИИ-агента, отмените выбор или нажмите Enter, чтобы пропустить этот шаг.

Подробнее о навыках агентов и других возможностях ИИ читайте в разделе ИИ.

#Текущая директория

Чтобы создать проект в текущем каталоге, введите . в качестве пути к проекту, когда будет предложено:

◆  Create Rspress Project

◇  Project name or path
│  .

Если текущий каталог не пуст, CLI спросит, следует ли продолжить и перезаписать файлы.

#Неинтерактивный режим

Вы можете передать параметры CLI для создания проекта без интерактивных подсказок:

npx -y create-rspress@latest my-docs --template basic-theme --tools rslint,prettier

Вы также можете создать многоязычный шаблон:

npx -y create-rspress@latest my-docs --template i18n

Или создайте многоязычный сайт с папкой theme:

npx -y create-rspress@latest my-docs --template i18n-theme

Вы также можете явно добавить навыки агента:

npx -y create-rspress@latest my-docs --template basic-theme --skill rspress-docs-generator,rspress-best-practices,rspress-description-generator

Все флаги CLI, поддерживаемые create-rspress:

Usage: create-rspress [dir] [options]

Options:

  -h, --help                display help for command
  -d, --dir <dir>           create project in specified directory
  -t, --template <tpl>      specify the template to use
  --no-git                  skip Git repository initialization
  --tools <tool>            add additional tools, comma separated
  --skill <skill>           add optional skills, comma separated
  --override                override files in target directory
  --packageName <name>      specify the package name
  --template-version <ver>  specify the npm template version

Available templates:
  basic, basic-theme, i18n, i18n-theme

Optional tools:
  eslint, rslint, biome, prettier

Optional skills:
  rspress-docs-generator, rspress-best-practices, rspress-custom-theme, rspress-description-generator

#Ручная настройка

Если вы хотите добавить Rspress в существующий проект или самостоятельно создать минимальные файлы, начните с создания каталога:

mkdir rspress-app && cd rspress-app

Создайте package.json:

npm init -y

Установите Rspress:

npm install @rspress/core -D

yarn add @rspress/core -D

pnpm add @rspress/core -D

bun add @rspress/core -D

deno add npm:@rspress/core -D

Создайте первую страницу:

mkdir docs && echo '# Привет, мир!' > docs/index.md

Добавьте (или обновите) секцию scripts в package.json:

{
  "scripts": {
    "dev": "rspress dev",
    "build": "rspress build",
    "preview": "rspress preview"
  }
}

Создайте файл конфигурации:

import { defineConfig } from '@rspress/core';

export default defineConfig({
  root: 'docs',
});

Создайте tsconfig.json:

{
  "compilerOptions": {
    "lib": ["DOM", "ES2023"],
    "jsx": "react-jsx",
    "target": "ES2023",
    "noEmit": true,
    "skipLibCheck": true,
    "useDefineForClassFields": true,

    /* modules */
    "module": "ESNext",
    "moduleDetection": "force",
    "moduleResolution": "bundler",
    "verbatimModuleSyntax": true,
    "resolveJsonModule": true,
    "allowImportingTsExtensions": true,
    "noUncheckedSideEffectImports": true,
    "isolatedModules": true,

    /* type checking */
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true
  },
  "include": ["docs", "theme", "rspress.config.ts"],
  "mdx": {
    "checkMdx": true
  }
}

#Запуск dev-сервера

Запустите локальный сервер разработки следующей командой:

npm run dev

yarn run dev

pnpm run dev

bun run dev

deno run npm:dev

#Сборка для продакшена

Соберите продакшен-версию сайта следующей командой:

npm run build

yarn run build

pnpm run build

bun run build

deno run npm:build

По умолчанию Rspress использует папку doc_build как директорию вывода.

#Локальный предпросмотр

Запустите локальный сервер предпросмотра следующей командой:

npm run preview

yarn run preview

pnpm run preview

bun run preview

deno run npm:preview

Превью-сервер обслуживает скомпилированные файлы рабочей версии сайта из doc_build.

#Следующие шаги

• Изучите раздел Базовые возможности, чтобы узнать о маршрутизации, главных страницах, статических ресурсах, развёртывании и других общих функциях сайта документации.
• Изучите раздел Использование MDX, чтобы узнать, как писать MDX и использовать компоненты в документации.
• Изучите раздел Конфигурация, чтобы узнать все поддерживаемые параметры конфигурации Rspress.