Nextra 3.0 がリリースされました。 詳細はこちら

テーマ設定

テーマはtheme.config.jsxファイルで設定します。設定を含むオブジェクトをエクスポートする必要があります。例:

theme.config.jsx
export default {
  project: {
    link: 'https://github.com/shuding/nextra'
  },
  logo: <b>Project</b>
}

各オプションの詳細を以下に示します。

グローバル

ドキュメントリポジトリ

ドキュメントのリポジトリのURLを設定します。「このページを編集」リンクと「フィードバック」リンクを生成するために使用されます。

オプション説明
docsRepositoryBasestringドキュメントリポジトリのURL

パスの指定

ドキュメントがモノレポ、サブフォルダ、またはリポジトリの異なるブランチ内にある場合は、docsRepositoryBaseをドキュメントのpages/フォルダのルートパスに設定するだけで済みます。例:

theme.config.jsx
export default {
  docsRepositoryBase: 'https://github.com/shuding/nextra/tree/main/docs'
}

すると、Nextraはすべてのページの正しいファイルパスを自動的に生成します。

Headタグ

Webサイトの<head>タグを設定します。メタタグ、タイトル、ファビコンなどを追加できます。

オプション説明
headReact.ReactNode | React.FC<head>コンテンツをレンダリングするコンポーネント

静的なHeadタグ

静的なheadタグのみの場合は、headに直接配置するのが簡単です。例:

theme.config.jsx
export default {
  head: (
    <>
      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
      <meta property="og:title" content="Nextra" />
      <meta property="og:description" content="The next site builder" />
    </>
  )
}

ページに基づいた動的なタグ

現在のページのフロントマターに基づいてheadタグを動的に生成するために、headとして関数コンポーネントを使用することもできます。例:

theme.config.jsx
import { useRouter } from 'next/router'
import { useConfig } from 'nextra-theme-docs'
 
export default {
  head() {
    const { asPath, defaultLocale, locale } = useRouter()
    const { frontMatter } = useConfig()
    const url =
      'https://my-app.com' +
      (defaultLocale === locale ? asPath : `/${locale}${asPath}`)
 
    return (
      <>
        <meta property="og:url" content={url} />
        <meta property="og:title" content={frontMatter.title || 'Nextra'} />
        <meta
          property="og:description"
          content={frontMatter.description || 'The next site builder'}
        />
      </>
    )
  }
}

useConfigフックとfrontMatterオブジェクトの詳細については、useConfig APIセクションを参照してください。

ダークモードとテーマ

Webサイトのテーマの動作をカスタマイズします。

オプション説明
darkModebooleanダークモードの切り替えボタンを表示または非表示にします
nextThemesobjectnext-themesパッケージの設定

テーマカラー

ライトテーマとダークテーマのプライマリ色相と彩度の値を設定することで、Webサイトのテーマカラーを調整できます。

オプション説明
color.huenumber | { dark: number; light: number }プライマリテーマカラーの色相
color.saturationnumber | { dark: number; light: number }プライマリテーマカラーの彩度
backgroundColor.darkRRR,GGG,BBB形式のstringライトテーマの背景色
backgroundColor.lightRRR,GGG,BBB形式のstringダークテーマの背景色

このWebサイトでお試しください

色相彩度

ナビゲーションバーにレンダリングされるWebサイトのロゴ。Reactノードまたは関数コンポーネントにすることができます。

オプション説明
logoReact.ReactNode | React.FCWebサイトのロゴ
logoLinkboolean | stringロゴのリンク
Customized Logo
theme.config.jsx
export default {
  logo: (
    <>
      <svg width="24" height="24" viewBox="0 0 24 24">
        <path
          fill="currentColor"
          d="M14.683 14.828a4.055 4.055 0 0 1-1.272.858a4.002 4.002 0 0 1-4.875-1.45l-1.658 1.119a6.063 6.063 0 0 0 1.621 1.62a5.963 5.963 0 0 0 2.148.903a6.035 6.035 0 0 0 3.542-.35a6.048 6.048 0 0 0 1.907-1.284c.272-.271.52-.571.734-.889l-1.658-1.119a4.147 4.147 0 0 1-.489.592z M12 2C6.486 2 2 6.486 2 12s4.486 10 10 10s10-4.486 10-10S17.514 2 12 2zm0 2c2.953 0 5.531 1.613 6.918 4H5.082C6.469 5.613 9.047 4 12 4zm0 16c-4.411 0-8-3.589-8-8c0-.691.098-1.359.264-2H5v1a2 2 0 0 0 2 2h2a2 2 0 0 0 2-2h2a2 2 0 0 0 2 2h2a2 2 0 0 0 2-2v-1h.736c.166.641.264 1.309.264 2c0 4.411-3.589 8-8 8z"
        />
      </svg>
      <span style={{ marginLeft: '.4em', fontWeight: 800 }}>
        My Cool Project
      </span>
    </>
  )
}

ナビゲーションバーにプロジェクトのホームページにリンクするボタンを表示します。デフォルトでは、NextraのGitHubリポジトリにリンクします。

オプション説明
project.linkstringプロジェクトホームページのURL
project.iconReact.ReactNode | React.FCプロジェクトリンクのアイコンまたは要素

project.linkproject.iconを設定して、プロジェクトリンクをカスタマイズできます。たとえば、GitLabリポジトリにリンクするようにします。

Project link
theme.config.jsx
export default {
  project: {
    link: 'https://gitlab.com/inkscape/inkscape',
    icon: (
      <svg width="24" height="24" fill="currentColor" viewBox="0 0 256 256">
        <path d="m231.9 169.8l-94.8 65.6a15.7 15.7 0 0 1-18.2 0l-94.8-65.6a16.1 16.1 0 0 1-6.4-17.3L45 50a12 12 0 0 1 22.9-1.1L88.5 104h79l20.6-55.1A12 12 0 0 1 211 50l27.3 102.5a16.1 16.1 0 0 1-6.4 17.3Z" />
      </svg>
    )
  }
}

iconがない場合は、デフォルトでGitHubアイコンになります。

ナビゲーションバーにプロジェクトのフォーラムまたはその他のソーシャルメディアにリンクするボタンを表示します。

オプション説明
chat.linkstringチャットリンクのURL
chat.iconReact.ReactNode | React.FCチャットリンクのアイコンまたは要素

chat.linkchat.iconを設定して、チャットリンクをカスタマイズできます。たとえば、Twitterアカウントにリンクするようにします。

theme.config.jsx
export default {
  chat: {
    link: 'https://twitter.com/shuding_',
    icon: (
      <svg width="24" height="24" viewBox="0 0 248 204">
        <path
          fill="currentColor"
          d="M221.95 51.29c.15 2.17.15 4.34.15 6.53 0 66.73-50.8 143.69-143.69 143.69v-.04c-27.44.04-54.31-7.82-77.41-22.64 3.99.48 8 .72 12.02.73 22.74.02 44.83-7.61 62.72-21.66-21.61-.41-40.56-14.5-47.18-35.07a50.338 50.338 0 0 0 22.8-.87C27.8 117.2 10.85 96.5 10.85 72.46v-.64a50.18 50.18 0 0 0 22.92 6.32C11.58 63.31 4.74 33.79 18.14 10.71a143.333 143.333 0 0 0 104.08 52.76 50.532 50.532 0 0 1 14.61-48.25c20.34-19.12 52.33-18.14 71.45 2.19 11.31-2.23 22.15-6.38 32.07-12.26a50.69 50.69 0 0 1-22.2 27.93c10.01-1.18 19.79-3.86 29-7.95a102.594 102.594 0 0 1-25.2 26.16z"
        />
      </svg>
    )
  }
}

iconがない場合は、デフォルトでDiscordアイコンになります。

ナビゲーションバーにカスタムメニューまたはリンクを追加する方法については、ページ設定を確認してください。

オプション説明
search.componentReact.ReactNode |
React.FC<{ className?: string; directories: Item[] }>
search.emptyResultReact.ReactNode | React.FC見つからない場合のテキスト
search.loadingReact.ReactNode | React.FC読み込み中のテキスト
search.errorstring | (() => string)エラーテキスト
search.placeholderstring | (() => string)プレースホルダーテキスト

Webサイトの上部にバナーを表示します。警告や通知を表示するために使用できます。

オプション説明
banner.dismissibleboolean閉じることのできるバナーかどうか
banner.keystringバナーの状態(非表示または非表示でない)を保持するためのストレージキー
banner.contentReact.ReactNode | React.FCバナーの内容

バナーは非表示にすることができます。デフォルトでは、banner.key"nextra-banner"となり、クライアントのバナーの状態(非表示または非表示でない)を保持するためにlocalStorageで使用されます。

バナーテキストを更新した場合は、必ずキーを変更して、バナーが再度表示されるようにする必要があります。常に現在のテキストに対して説明的なキーを使用するのがベストプラクティスです。例:

Banner
theme.config.jsx
export default {
  banner: {
    key: '2.0-release',
    content: (
      <a href="https://nextra.dokyumento.jp" target="_blank">
        🎉 Nextra 2.0 is released. Read more →
      </a>
    )
  }
}

ナビゲーションバーのカスタマイズ

ナビゲーションバーコンポーネント全体をカスタマイズします。

オプション説明
navbar.componentReact.ReactNode | React.FC<NavBarProps>ナビゲーションバーコンポーネント
navbar.extraContentReact.ReactNode | React.FC最後のアイコンの後に追加コンテンツを表示します
オプション説明
sidebar.defaultMenuCollapseLevelnumber左側のメニューがデフォルトで折りたたまれるフォルダーレベルを指定します。デフォルトは 2 です。
sidebar.autoCollapsebooleantrue の場合、defaultMenuCollapseLevel より上の非アクティブなフォルダーを自動的に折りたたみます。
sidebar.toggleButtonbooleanサイドバーのトグルボタンを非表示/表示します。デフォルトは false です。

デフォルトでは、サイドバーメニューはレベル 2 で折りたたまれます。sidebar.defaultMenuCollapseLevel を別の数値に設定することで変更できます。たとえば、1 に設定すると、すべてのフォルダーがデフォルトで折りたたまれ、Infinity に設定すると、すべてのネストされたフォルダーがデフォルトで展開されます。

sidebar.autoCollapsetrue に設定されている場合、アクティブ/フォーカスされたルートを含まないすべてのフォルダーは、sidebar.defaultMenuCollapseLevel で設定されたレベルまで自動的に折りたたまれます。たとえば、defaultMenuCollapseLevel2 の場合、最上位のフォルダーは自動的に折りたたまれません。

サイドバーコンテンツのカスタマイズ

区切り線項目とともに、JSX 要素を使用してサイドバーコンテンツのレンダリング方法をカスタマイズできます。

_meta.jsx
export default {
  index: 'Intro',
  '--': {
    type: 'separator',
    title: (
      <div className="flex items-center gap-2">
        <MyLogo />
        {children}
      </div>
    )
  },
  frameworks: 'JS Frameworks & Libs',
  about: 'About'
}
Customized Sidebar

Frontmatter を使用したサイドバーのカスタマイズ

さらに、フロントマターの sidebarTitle プロパティを使用して、サイドバーのタイトルをカスタマイズできます。

pages/getting-started.mdx
---
sidebarTitle: Getting Started 🚀
---

サイドバータイトルの優先順位は次のとおりです。

  1. _meta.js ファイルの title プロパティ
  2. フロントマターの sidebarTitle
  3. フロントマターの title
  4. Title でフォーマットされたページのファイル名

コンテンツ

MDX コンポーネント

コンテンツをレンダリングするためのカスタム MDX コンポーネントを提供します。たとえば、カスタム pre コンポーネントを使用してコードブロックをレンダリングできます。

オプション説明
componentsRecord<string, React.FC>カスタム MDX コンポーネント

記述方向

ウェブサイトのデフォルトの記述方向。

オプション説明
direction"ltr" | "rtl"デフォルトの記述方向

メインコンテンツ

ページメイン領域の上部および/または下部のコンテンツをレンダリングします。コメントセクション、ニュースレターフォーム、またはその他の種類のコンテンツをレンダリングするために使用できます。

オプション説明
mainReact.FC<{ children: React.ReactNode }>メインコンテンツのコンポーネント

TOC サイドバー

目次

ページ右側に目次を表示します。見出し間を移動するのに便利です。

オプション説明
toc.componentReact.ReactNode | React.FC<TOCProps>TOC のカスタムレンダラー
toc.extraContentReact.ReactNode | React.FCTOC コンテンツの下に追加コンテンツを表示します
toc.floatbooleanコンテンツの横に TOC をフロート表示します
toc.titleReact.ReactNode | React.FCTOC サイドバーのタイトル。デフォルトは「このページの内容」です。
toc.backToTopReact.ReactNode | React.FC一番上までスクロール ボタンのテキスト

フローティング TOC

toc.float はデフォルトで有効になっています。有効にすると、TOC はページの右側に表示され、スクロール時に固定されます。無効にすると、TOC はページサイドバーに直接表示されます。

GitHub(または他の場所)のファイル URL を指す「このページを編集」リンクをページに表示します。

オプション説明
editLink.contentReact.ReactNode | React.FC編集リンクのコンテンツ
editLink.componentReact.FC<{ children: React.ReactNode; className?: string; filePath?: string }> | nullカスタマイズされた編集リンクコンポーネント

無効にするには、editLink.componentnull に設定できます。

組み込みのフィードバックリンクは、ユーザーがドキュメントに関するフィードバックを送信する方法を提供します。デフォルトでは、ドキュメントリポジトリの issue 作成フォームを指すリンクであり、現在のウェブサイトのタイトルが事前に入力されています。

オプション説明
feedback.contentReact.ReactNode | React.FCフィードバックボタンのコンテンツ
feedback.labelsstring新規作成された GitHub issue に追加できるラベル
feedback.useLink() => stringカスタムリンク。デフォルトでは、docsRepositoryBase で設定されたリポジトリで issue が開かれます。

無効にするには、feedback.contentnull に設定できます。

ページの末尾

コンテンツの下部に前のページと次のページのリンクを表示します。ページ間を移動するのに便利です。

オプション説明
navigationboolean | objectナビゲーションリンクを有効または無効にします
navigation.prevboolean前のページのリンクを有効または無効にします
navigation.nextboolean次のページのリンクを有効または無効にします
Navigation
theme.config.jsx
export default {
  navigation: {
    prev: true,
    next: true
  }
}

上記は、navigation: true と同等です。

最終更新日

各ページの最終更新日を表示します。コンテンツの鮮度を示すのに便利です。

オプション説明
gitTimestampReact.ReactNode | React.FC<{ timestamp: Date }>最終更新情報をレンダリングするコンポーネント

ウェブサイトのフッター領域。デフォルトのフッターにコンテンツを指定するか、カスタムコンポーネントで完全にカスタマイズできます。

オプション説明
footer.contentReact.ReactNode | React.FCフッターコンポーネントのコンテンツ
footer.componentReact.ReactNode | React.FC<{ menu: boolean }>カスタマイズされたフッターコンポーネント

著作権情報などの簡単なコンテンツをデフォルトのフッターに追加できます

theme.config.jsx
export default {
  footer: {
    content: (
      <span>
        MIT {new Date().getFullYear()} ©{' '}
        <a href="https://nextra.dokyumento.jp" target="_blank">
          Nextra
        </a>
        .
      </span>
    )
  }
}

テーマ切り替え

オプション説明
themeSwitch.componentReact.ReactNode |
React.FC<{ lite?: boolean, className?: string }>
テーマ切り替えをレンダリングするコンポーネント
themeSwitch.useOptionsThemeOptions | () => ThemeOptionsテーマ切り替えのオプション

オプション

ローカライズまたはその他の目的でオプション名をカスタマイズできます。

theme.config.jsx
export default {
  themeSwitch: {
    useOptions() {
      return {
        light: 'Light',
        dark: 'Dark',
        system: 'System'
      }
    }
  }
}

ページが見つかりません

ページが見つからない場合の破損リンクのレポートを構成するためのオプション。

オプション説明
notFound.contentReactNode | FCデフォルト:破損したリンクに関する問題を送信 →
notFound.labelsstringデフォルト:bug

I18n

i18n ドキュメントウェブサイトの言語ドロップダウンを構成するためのオプション。

オプション説明
i18n[number].localestringnext.config ファイルの i18n.locales フィールドからのロケール
i18n[number].namestringドロップダウンのロケール名
i18n[number].direction'ltr' | 'rtl'ロケールの記述方向。デフォルト:ltr

ファビコングリフ

これはすべてのブラウザでサポートされているわけではありませんが、絵文字または文字を使用するだけでウェブサイトのファビコンをカスタマイズするのに最適な方法です。

オプション説明
faviconGlyphstringファビコンとして使用するグリフ