Пользовательская тема

Тема в Nextra работает как слой, который будет отображаться как оболочка для всех страниц. В этой документации вы узнаете о процессе создания пользовательской темы.

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

(opens in a new tab)

Создание и настройка темы

Настройте Nextra под вашу тему

Вначале, вы должны сообщить Nextra, что хотите использовать собственную тему вместо предустановленных. Для этого в конфигурационном файле next.config.js укажите путь к файлу с вашей темой:

next.config.js

const withNextra = require('nextra')({
  theme: './theme.tsx',
})
 
module.exports = withNextra({
  // Other Next.js configurations
  ...
})

Создайте базовый контент

Вы уже можете работать в вашей теме! В корневой директории создайте корреспондирующий файл theme.tsx с базовым контентом:

theme.tsx

import type { NextraThemeLayoutProps } from 'nextra'
 
export default function Layout({ children }: NextraThemeLayoutProps) {
  return (
    <div>
      <h1>My Theme</h1>
      <div style={{ border: '1px solid' }}>{children}</div>
    </div>
  )
}

Эта функция принимает свойства children, которые являются MDX контентом текущей страницы, и оболочкой для некоторых других элементов контента. После создания темы от вас потребуется лишь добавить MDX файл pages/index.mdx. Результат можно отслеживать локально на вашем компьютере, используя 3000 порт (localhost:3000):

Nextra Custom Theme screenshot

Внутри вашей темы вы можете применить собственные CSS стили или стилизовать страницу иным способом. Для этого используйте импорт стилей. Хуки Next.js такие как useRouter и Head также доступны.

Укажите метаданные для активной страницы

Помимо children в тему также передаются и некоторые другие полезные свойства. С помощью pageOpts тема может получить доступ к метаданным (Metadata) страницы.

Для примера применим следующие фичи:

Укажем заголовок страницы в теге <title>
Отобразим простое содержание
Добавим метатег для og:image на клиенте

theme.tsx

import Head from 'next/head'
import type { NextraThemeLayoutProps } from 'nextra'
 
export default function Layout({ children, pageOpts }: NextraThemeLayoutProps) {
  const { title, frontMatter, headings } = pageOpts
 
  return (
    <div>
      <Head>
        <title>{title}</title>
        <meta name="og:image" content={frontMatter.image} />
      </Head>
      <h1>My Theme</h1>
      Table of Contents:
      <ul>
        {headings.map(heading => (
          <li key={heading.value}>{heading.value}</li>
        ))}
      </ul>
      <div style={{ border: '1px solid' }}>{children}</div>
    </div>
  )
}

Используйте Page Map для всего сайта

Отныне вы можете использовать 'pageMap', если хотите отобразить что-то вроде боковой панели (sidebar) или панели навигации (nav bar), которые передают информацию не только о текущей странице, но также и о других страницах.

Например, мы можем отобразить простой список всех страниц в верхнем меню:

theme.tsx

import Link from 'next/link'
import type { NextraThemeLayoutProps } from 'nextra'
 
export default function Layout({ children, pageOpts }: NextraThemeLayoutProps) {
  const { pageMap } = pageOpts
 
  return (
    <div>
      <h1>My Theme</h1>
      {pageMap.map(item => {
        if (item.kind === 'MdxPage') {
          return (
            <Link key={item.name} href={item.route}>
              {item.route}
            </Link>
          )
        }
        return null
      })}
      <div style={{ border: '1px solid' }}>{children}</div>
    </div>
  )
}

Также существуют и другие типы элементов, такие как Folder (для директорий) и Meta (для _meta.json). Все элементы типизированы, поэтому вы легко можете изменять их свойства.

Продвинутое использование

⚠️

Данная информация находится в разработке (opens in a new tab).

Быстрый старт Подробности о Nextra ↗