Тема для документации

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

Этот сайт и сайт Nextra (opens in a new tab) используют тему для документации.

Установка темы

Деплой на Vercel

Начните создавать сайт на Nextra. Для этого перейдите по ссылке, чтобы подключить свой Github-репозиторий к Vercel:

Vercel создаст отдельный экземпляр Темы для документации (opens in a new tab) и развернет ваш сайт в сети. После этого каждый коммит в вашем Github-репозитории будет автоматически отображаться на сайте.

Установка шаблона

Вы также можете установить шаблон (opens in a new tab) вручную.

Запуск проекта

Установите зависимости

Для запуска проекта потребуются Next.js, React, Nextra, и Nextra Docs Theme. Для этого в корневой директории вашего проекта установите следующие зависимости:

npm i next react react-dom nextra nextra-theme-docs

💡

Если в вашем проекте уже установлен Next.js, то вам потребуются только nextra и nextra-theme-docs в качестве расширений (add-ons).

Добавьте следующий код в файл package.json:

package.json

"scripts": {
  "dev": "next",
  "build": "next build",
  "start": "next start"
},

Вы можете запустить виртуальный сервер в режиме разработки, используя команду npm run dev (если вы пользуетесь пакетным менеджером npm), а для подготовки файлов к деплою – npm run build && npm run start.

💡

Если вы не знакомы с Next.js, обратите внимание, что режим разработки значительно медленнее, поскольку Next.js компилирует каждую страницу, на которую вы переходите, в отдельности.

Добавьте Next.js Config

В корневой директории вашего проекта создайте файлnext.config.js:

next.config.js

const withNextra = require('nextra')({
  theme: 'nextra-theme-docs',
  themeConfig: './theme.config.jsx'
})
 
module.exports = withNextra()
 
// Если вы используете другие конфигурации Next.js, то можете передать их в качестве параметра:
// module.exports = withNextra({ /* другие конфигурации next.js */ })

При использовании описанной выше конфигурации Nextra сможет обрабатывать файлы Markdown в вашем Next.js проекте с установленной темой. Другие конфигурации Nextra вы можете посмотреть в "Настройках Nextra".

Создайте Docs Theme Config

Наконец, в корневой директории вашего проекта создайте корреспондирующий файл theme.config.jsx. Он сконфигурирует Тему для документации:

theme.config.jsx

export default {
  logo: <span>My Nextra Documentation</span>,
  project: {
    link: 'https://github.com/shuding/nextra'
  }
  // ... другие настройки темы
}

Список доступных конфигураций темы для документации смотрите здесь.

Наполните сайт контентом

Теперь вы можете создать свой первый MDX файл с контентом. Например, pages/index.mdx:

pages/index.mdx

# Добро пожаловать в Nextra
 
Привет, мир!

Затем запустите ваш сайт в режиме разработки. Используйте команды next или next dev (в зависимости от того, какая из них указана в package.json). 🎉

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

Настройки страниц Настройки темы Компоненты API

Тема для документации Настройки страниц