Настройки страниц

В Nextra структуру сайта и страниц можно настроить с помощью файлов _meta.json. Тема для документации предоставляет несколько дополнительных конфигурационных опций.

Эти опции определяют общий вид темы, в особенности панель навигации и боковую панель.

Страницы

Заголовок и порядок отображения списка страниц в боковой панели настраиваются в файлах _meta.json в формате "ключ-значение".

Допустим, что у вас имеется следующая файловая структура:

Переопределить вид и подрядок отображения списка страниц в боковой панели можно в файле _meta.json:

{
  "index": "Главная страница",
  "contact": "Контакты",
  "about": "О компании"
}

Папки

Папки можно настроить также, как и страницы. Например:

Файл _meta.json верхнего уровня содержит метаданные для страниц и папок верхнего уровня:

{
  "index": "My Homepage",
  "contact": "Contact Us",
  "fruits": "Delicious Fruits",
  "about": "About Us"
}

А вложенный файл _meta.json содержит метаданные страниц, находящихся в той же директории:

{
  "apple": "Apple",
  "banana": "Banana"
}

Таким образом, информация генерируется в катологах, которые можно свободно перемещать, не изменяя при этом сам файл _meta.json.

Папки с индексной страницей

Что если мы захотим создать папку с индексной страницей? Можно довабить страницу MDX с тем же названием и в тот же каталог, что и папка. Допустим, мы хотим добавить /fruits в приведенный выше пример. Можно создать fruits.mdx в разделе "Страницы":

В этом случае Nextra будет понимать, что ключ fruits в _meta.json определяет папку с индексной страницей. Если кликнуть на эту папку в боковой панели, она развернет свое содержимое и покажет страницу fruits.mdx.

Внешние ссылки

В боковую панель можно добавить внешние ссылки. Для этого в файле _meta.json нужно указать параметр href:

{
  "index": "My Homepage",
  "contact": "Contact Us",
  "fruits": "Delicious Fruits",
  "about": "About Us",
  "github_link": {
    "title": "Nextra",
    "href": "https://github.com/shuding/nextra"
  }
}

Для того, чтобы ссылка открывалась в новой вкладке, нужно активировать опцию "newWindow": true:

{
  "index": "My Homepage",
  "contact": "Contact Us",
  "fruits": "Delicious Fruits",
  "about": "About Us",
  "github_link": {
    "title": "Nextra",
    "href": "https://github.com/shuding/nextra",
    "newWindow": true
  }
}

Скрытые маршруты

По умолчанию все MDX маршруты (routes) файловой ситемы отображаются на боковой панели. Но, существует возможность скрыть определенные страницы и папки с помощью опции "display": "hidden":

{
  "index": "My Homepage",
  "contact": {
    "display": "hidden"
  },
  "about": "About Us"
}

В этом случае страница по-прежнему будет доступна по URL-адресу /contact, но не будет отображаться на боковой панели.

Элементы навигационной панели

Дополнительные документы

Если вы определите страницу или папку верхнего уровня как "type": "page", она будет отображаться как специальная страница в панели навигации, а не на боковой панели. С помощью этой функции вы можете создать несколько «поддокументов» и специальных страниц или ссылок, таких как «Свяжитесь с нами», которые всегда будут видны.

Например, в вашем проекте могут быть 2 папки с документами frameworks и fruits:

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

{
  "index": {
    "title": "Home",
    "type": "page"
  },
  "frameworks": {
    "title": "Frameworks",
    "type": "page"
  },
  "fruits": {
    "title": "Fruits",
    "type": "page"
  },
  "about": {
    "title": "About",
    "type": "page"
  }
}

Вот как это будет выглядеть:

Также вы можете скрыть ссылки, подобные Home, на панели навигации с помощью опции "display": "hidden".

Выпадающее меню

На панель навигации можно добавить выпадающее меню, используя опции "type": "menu" и "items":

{
  "company": {
    "title": "Company",
    "type": "menu",
    "items": {
      "about": {
        "title": "About",
        "href": "/about"
      },
      "contact": {
        "title": "Contact Us",
        "href": "mailto:hi@example.com"
      }
    }
  }
}

Ссылки

Внешние ссылки также можно добавить на навигационную панель:

{
  "index": {
    "title": "Home",
    "type": "page"
  },
  "about": {
    "title": "About",
    "type": "page"
  },
  "contact": {
    "title": "Contact Us",
    "type": "page",
    "href": "https://example.com/contact",
    "newWindow": true
  }
}

Запасные варианты (Fallbacks)

В приведенном выше примере с Поддокументами параметр "type": "page" необходимо задавать для каждой страницы. Эту задачу можно упростить, используя ключ "*" для определения резервной конфигурации всех элементов в папке:

{
  "*": {
    "type": "page"
  },
  "index": "Home",
  "frameworks": "Frameworks",
  "fruits": "Fruits",
  "about": "About"
}

Они эквивалентны тем, где используется "type": "page".

Разделители

Возможно использовать элемент "плейсхолдер" с параметром "type": "separator" для создания разделительной линии между элементами на боковой панели:

{
  "index": "My Homepage",
  "---": {
    "type": "separator"
  },
  "contact": "Contact Us"
}

Дополнительно

Компоненты темы

Вы можете настроить тему для каждой страницы с помощью опции "theme". Например, можно отключить или включить определенные компоненты для конкретных страниц:

{
  "index": {
    "title": "Home",
    "theme": {
      "breadcrumb": false,
      "footer": true,
      "sidebar": false,
      "toc": true,
      "pagination": false
    }
  }
}

Этот параметр будет наследоваться всеми дочерними страницами, если он задан для папки.

Макеты

По умолчанию в конфигурации темы каждой страницы установлен параметр "layout": "default".

Исходный макет

По умолчанию Nextra отображает содержимое MDX-файлов (например, h1, h2, h3 и т.д.) с помощью тематических компонентов внутри контейнера содержимого. Допустимо использовать значение "raw", чтобы запретить Nextra добавлять стили к содержимому:

{
  "index": {
    "title": "Home",
    "theme": {
      "layout": "raw"
    }
  }
}

Широкий макет

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

{
  "index": {
    "title": "Home",
    "theme": {
      "layout": "full"
    }
  }
}

Форматирование текста

Опция "typesetting" управляет такими параметрами форматирования, как особенности шрифта, стили заголовков и компоненты li и code. В теме для документации доступны параметры "default" и "article".

Шрифт по умолчанию подходит для большинства случаев, например, для документации, но вы можете использовать "article" для оформления, чтобы оно выглядело как элегантная страница со статьей:

{
  "about": {
    "title": "About Us",
    "theme": {
      "typesetting": "article"
    }
  }
}