- {config.i18n ? (
+ {config.i18n.length > 0 && (
- ) : null}
+ )}
{config.darkMode ? (
diff --git a/packages/nextra-theme-docs/src/components/toc.tsx b/packages/nextra-theme-docs/src/components/toc.tsx
index d2f4d2aff3..46519ac67a 100644
--- a/packages/nextra-theme-docs/src/components/toc.tsx
+++ b/packages/nextra-theme-docs/src/components/toc.tsx
@@ -2,41 +2,18 @@ import React, { ReactElement, useEffect, useRef, useMemo } from 'react'
import cn from 'clsx'
import Slugger from 'github-slugger'
import { Heading } from 'nextra'
-import parseGitUrl from 'parse-git-url'
import scrollIntoView from 'scroll-into-view-if-needed'
import { renderComponent, getHeadingText, getGitIssueUrl } from '../utils'
import { useConfig, useActiveAnchor } from '../contexts'
import { Anchor } from './anchor'
-const getEditUrl = (filepath?: string): string => {
- const config = useConfig()
- const repo = parseGitUrl(config.docsRepositoryBase || '')
- if (!repo) throw new Error('Invalid `docsRepositoryBase` URL!')
-
- switch (repo.type) {
- case 'github':
- return `https://github.com/${repo.owner}/${repo.name}/blob/${
- repo.branch || 'main'
- }/${repo.subdir || 'pages'}${filepath}`
- case 'gitlab':
- return `https://gitlab.com/${repo.owner}/${repo.name}/-/blob/${
- repo.branch || 'main'
- }/${repo.subdir || 'pages'}${filepath}`
- }
-
- return '#'
+export type TOCProps = {
+ headings: Heading[]
+ filePath: string
}
-export function TOC({
- headings,
- filepathWithName,
- className
-}: {
- headings: Heading[]
- filepathWithName: string
- className: string
-}): ReactElement {
+export function TOC({ headings, filePath }: TOCProps): ReactElement {
const slugger = new Slugger()
const activeAnchor = useActiveAnchor()
const config = useConfig()
@@ -60,8 +37,9 @@ export function TOC({
)
const hasHeadings = items.length > 0
- const hasMetaInfo =
- config.feedbackLink || config.footerEditLink || config.tocExtraContent
+ const hasMetaInfo = Boolean(
+ config.feedback.link || config.editLink.component || config.toc.extraContent
+ )
const activeSlug = Object.entries(activeAnchor).find(
([, { isActive }]) => isActive
@@ -88,8 +66,8 @@ export function TOC({
)
return (
-
{hasHeadings && (
<>
-
On This Page
+
+ {renderComponent(config.toc.title)}
+
{items.map(({ slug, text, depth }) => (
-
@@ -125,7 +105,7 @@ export function TOC({
)}
- {hasMetaInfo ? (
+ {hasMetaInfo && (
- {config.feedbackLink ? (
+ {config.feedback.link ? (
- {renderComponent(config.feedbackLink)}
+ {renderComponent(config.feedback.link)}
) : null}
- {config.footerEditLink ? (
-
- {renderComponent(config.footerEditLink)}
-
- ) : null}
+ {renderComponent(config.editLink.component, {
+ filePath,
+ className: linkClassName,
+ children: renderComponent(config.editLink.text)
+ })}
- {config.tocExtraContent
- ? renderComponent(config.tocExtraContent)
- : null}
+ {renderComponent(config.toc.extraContent)}
-
)
}
diff --git a/packages/nextra-theme-docs/src/constants.tsx b/packages/nextra-theme-docs/src/constants.tsx
index 1f6f90b478..837170d431 100644
--- a/packages/nextra-theme-docs/src/constants.tsx
+++ b/packages/nextra-theme-docs/src/constants.tsx
@@ -1,39 +1,68 @@
+/* eslint sort-keys: error */
import React from 'react'
import { DocsThemeConfig, PageTheme } from './types'
import { useRouter } from 'next/router'
+import { Anchor, Flexsearch, Footer, TOC } from './components'
+import { DiscordIcon, GitHubIcon } from 'nextra/icons'
+import { MatchSorterSearch } from './components/match-sorter-search'
+import { useConfig } from './contexts'
+import { getGitEditUrl } from './utils'
export const DEFAULT_LOCALE = 'en-US'
export const IS_BROWSER = typeof window !== 'undefined'
+export const META_FILENAME = '_meta.json'
+
export const DEFAULT_THEME: DocsThemeConfig = {
- projectLink: 'https://github.com/shuding/nextra',
- docsRepositoryBase: 'https://github.com/shuding/nextra',
- titleSuffix: ' – Nextra',
- nextLinks: true,
- prevLinks: true,
- search: true,
+ banner: {
+ key: 'nextra-banner',
+ text: ''
+ },
+ bodyExtraContent: null,
+ components: {},
darkMode: true,
- nextThemes: {
- defaultTheme: 'system',
- storageKey: 'theme'
+ direction: 'ltr',
+ docsRepositoryBase: 'https://github.com/shuding/nextra',
+ editLink: {
+ component({ className, filePath, children }) {
+ const editUrl = getGitEditUrl(filePath)
+ if (!editUrl) {
+ return null
+ }
+ return (
+
+ {children}
+
+ )
+ },
+ text: 'Edit this page'
+ },
+ feedback: {
+ labels: '',
+ link: null
},
- defaultMenuCollapsed: false,
// @TODO: Can probably introduce a set of options to use Google Fonts directly
- // font: true,
- footer: true,
- footerText: `MIT ${new Date().getFullYear()} © Nextra.`,
- footerEditLink: 'Edit this page',
- gitTimestamp: 'Last updated on',
- logo: (
- <>
-
Nextra
-
- The Next Docs Builder
-
-
- ),
- head: () => (
+ font: false,
+ footer: {
+ component: Footer,
+ text: `MIT ${new Date().getFullYear()} © Nextra.`
+ },
+ gitTimestamp({ timestamp }) {
+ const { locale = DEFAULT_LOCALE } = useRouter()
+ return (
+ <>
+ Last updated on{' '}
+ {timestamp.toLocaleDateString(locale, {
+ day: 'numeric',
+ month: 'long',
+ year: 'numeric'
+ })}
+
+ )
+ },
+ github: '',
+ head: (
<>
@@ -45,33 +74,92 @@ export const DEFAULT_THEME: DocsThemeConfig = {
),
- searchPlaceholder() {
- const { locale } = useRouter()
- if (locale === 'zh-CN') return '搜索文档...'
- return 'Search documentation...'
- },
- unstable_searchResultEmpty: (
-
- No results found.
-
+ i18n: [],
+ logo: (
+ <>
+
Nextra
+
+ The Next Docs Builder
+
+
),
- bannerKey: 'nextra-banner',
- notFoundLink: 'Submit an issue about broken link →',
- notFoundLabels: 'bug',
- serverSideErrorLink: 'Submit an issue about error in url →',
- serverSideErrorLabels: 'bug'
- // direction: 'ltr',
- // i18n: [{ locale: 'en-US', text: 'English', direction: 'ltr' }],
+ navigation: {
+ next: true,
+ prev: true
+ },
+ nextThemes: {
+ defaultTheme: 'system',
+ storageKey: 'theme'
+ },
+ notFound: {
+ labels: 'bug',
+ link: 'Submit an issue about broken link →'
+ },
+ project: {
+ icon: (
+ <>
+
+
GitHub
+
+ ),
+ // by default should be empty so clicking on project link will go to the github link
+ link: ''
+ },
+ projectChat: {
+ icon: (
+ <>
+
+
Discord
+
+ ),
+ link: ''
+ },
+ search: {
+ component({ className, directories }) {
+ const config = useConfig()
+ return config.unstable_flexsearch ? (
+
+ ) : (
+
+ )
+ },
+ emptyResult: (
+
+ No results found.
+
+ ),
+ placeholder() {
+ const { locale } = useRouter()
+ if (locale === 'zh-CN') return '搜索文档...'
+ return 'Search documentation...'
+ }
+ },
+ serverSideError: {
+ labels: 'bug',
+ link: 'Submit an issue about error in url →'
+ },
+ sidebar: {
+ defaultMenuCollapsed: false,
+ subtitle: null
+ },
+ titleSuffix: ' – Nextra',
+ toc: {
+ component: TOC,
+ extraContent: null,
+ float: true,
+ title: 'On This Page'
+ },
+ unstable_faviconGlyph: ''
}
export const DEFAULT_PAGE_THEME: PageTheme = {
+ breadcrumb: true,
+ footer: true,
+ layout: 'default',
navbar: true,
+ pagination: true,
sidebar: true,
+ timestamp: true,
toc: true,
- pagination: true,
- footer: true,
- layout: 'default',
- typesetting: 'default',
- breadcrumb: true,
- timestamp: true
+ typesetting: 'default'
}
diff --git a/packages/nextra-theme-docs/src/contexts/config.tsx b/packages/nextra-theme-docs/src/contexts/config.tsx
index 686a421db6..1caa64d7aa 100644
--- a/packages/nextra-theme-docs/src/contexts/config.tsx
+++ b/packages/nextra-theme-docs/src/contexts/config.tsx
@@ -14,16 +14,57 @@ import { MenuProvider } from './menu'
type Config = DocsThemeConfig &
Pick<
PageOpts,
- 'unstable_flexsearch' | 'newNextLinkBehavior' | 'title' | 'meta'
+ 'unstable_flexsearch' | 'newNextLinkBehavior' | 'title' | 'frontMatter'
>
const ConfigContext = createContext
({
title: '',
- meta: {}
+ frontMatter: {},
+ ...DEFAULT_THEME
})
export const useConfig = () => useContext(ConfigContext)
+const DEEP_OBJECT_KEYS = [
+ 'banner',
+ 'feedback',
+ 'footer',
+ 'navigation',
+ 'nextThemes',
+ 'notFound',
+ 'project',
+ 'projectChat',
+ 'search',
+ 'serverSideError',
+ 'sidebar',
+ 'toc'
+] as const
+
+const LegacyOptions: Record = {
+ projectLink: 'project.link',
+ projectLinkIcon: 'project.icon',
+ nextLinks: 'navigation.next',
+ prevLinks: 'navigation.prev',
+ defaultMenuCollapsed: 'sidebar.defaultMenuCollapsed',
+ footerText: 'footer.text',
+ footerEditLink: 'editLink.text',
+ floatTOC: 'toc.float',
+ feedbackLink: 'feedback.link',
+ feedbackLabels: 'feedback.labels',
+ customSearch: 'search.component',
+ searchPlaceholder: 'search.placeholder',
+ projectChatLink: 'projectChat.link',
+ projectChatLinkIcon: 'projectChat.icon',
+ sidebarSubtitle: 'sidebar.subtitle',
+ bannerKey: 'banner.key',
+ tocExtraContent: 'toc.extraContent',
+ unstable_searchResultEmpty: 'search.emptyResult',
+ notFoundLink: 'notFound.link',
+ notFoundLabels: 'notFound.labels',
+ serverSideErrorLink: 'serverSideError.link',
+ serverSideErrorLabels: 'serverSideError.labels'
+}
+
export const ConfigProvider = ({
children,
value
@@ -33,15 +74,50 @@ export const ConfigProvider = ({
}): ReactElement => {
const [menu, setMenu] = useState(false)
const { themeConfig, pageOpts } = value
- const extendedConfig = {
+ const extendedConfig: Config = {
...DEFAULT_THEME,
...themeConfig,
unstable_flexsearch: pageOpts.unstable_flexsearch,
newNextLinkBehavior: pageOpts.newNextLinkBehavior,
title: pageOpts.title,
- meta: pageOpts.meta
+ frontMatter: pageOpts.frontMatter,
+ ...Object.fromEntries(
+ DEEP_OBJECT_KEYS.map(key => [
+ key,
+ { ...DEFAULT_THEME[key], ...themeConfig[key] }
+ ])
+ )
+ }
+
+ const { nextThemes } = extendedConfig
+
+ if (process.env.NODE_ENV === 'development') {
+ const notice =
+ '[nextra-theme-docs] ⚠️ You are using legacy theme config option'
+
+ for (const [legacyOption, newPath] of Object.entries(LegacyOptions)) {
+ if (legacyOption in themeConfig) {
+ const [obj, key] = newPath.split('.')
+ const renameTo = key ? `${obj}: { ${key}: ... }` : obj
+ console.warn(`${notice} "${legacyOption}". Rename it to ${renameTo}`)
+ }
+ }
+
+ for (const key of ['search', 'footer'] as const) {
+ if (key in themeConfig) {
+ const option = themeConfig[key]
+ if (typeof option === 'boolean' || option == null) {
+ console.warn(
+ `${notice} "${key}".`,
+ option ? 'Remove it' : `Rename it to ${key}: { component: null }`
+ )
+ }
+ }
+ }
+ if (typeof themeConfig.banner === 'string') {
+ console.warn(notice, '"banner". Rename it to banner: { text: ... }')
+ }
}
- const nextThemes = extendedConfig.nextThemes || {}
return (
-
- {children}
-
+ {children}
)
diff --git a/packages/nextra-theme-docs/src/contexts/menu.ts b/packages/nextra-theme-docs/src/contexts/menu.ts
index 5c5ef24e42..53703b5e95 100644
--- a/packages/nextra-theme-docs/src/contexts/menu.ts
+++ b/packages/nextra-theme-docs/src/contexts/menu.ts
@@ -3,13 +3,11 @@ import { useContext, createContext, Dispatch, SetStateAction } from 'react'
interface Menu {
menu: boolean
setMenu: Dispatch>
- defaultMenuCollapsed: boolean
}
const MenuContext = createContext