Skip to content

Latest commit

 

History

History
599 lines (429 loc) · 10.9 KB

configuration.mdx

File metadata and controls

599 lines (429 loc) · 10.9 KB
Raw

import Callout from 'nextra-theme-docs/callout'

export const Unstable = () => ( This is an unstable and experimental feature and not recomended for general use. )

Configuration

To configure the theme, edit or create the theme.config.js file in the root directory. The file looks something like this:

/**
 * @type {import('nextra-theme-docs').DocsThemeConfig}
 */
export default {
  projectLink: 'https://gitlab.com/librewolf-community/browser',
  titleSuffix: ' – Nextra',
  footerText: `MIT ${new Date().getFullYear()} © Nextra.`
  // ...
}

projectLink

The URL that the button in the top right will point to.

Type: string

Default: https://github.com/shuding/nextra

Example:

/**
 * @type {import('nextra-theme-docs').DocsThemeConfig}
 */
export default {
  projectLink: 'https://gitlab.com/librewolf-community/browser'
}

github

The URL that the button in the top right will point to.

Type: string

Default: https://github.com/shuding/nextra

Example:

/**
 * @type {import('nextra-theme-docs').DocsThemeConfig}
 */
export default {
  github: 'https://gitlab.com/librewolf-community/browser'
}

projectLinkIcon

Changes the icon that is shown in the top right.

Type: ReactNode | React.FC<{ locale?: string }>{:ts}

Default: GitHub icon

Example:

import Gitlab from '@geist-ui/react-icons/gitlab'
/**
 * @type {import('nextra-theme-docs').DocsThemeConfig}
 */
export default {
  projectLinkIcon: ({ locale }) => <Gitlab />
}

docsRepositoryBase

The base URL of the GitHub repository the docs are located in. This will be used for the Edit this Page on GitHub button.

Type: string

Default: https://github.com/shuding/nextra

Example:

/**
 * @type {import('nextra-theme-docs').DocsThemeConfig}
 */
export default {
  docsRepositoryBase: 'https://github.com/shuding/nextra'
}

titleSuffix

Suffix that will be added to page titles in the URL bar.

Type: string

Default: – Nextra

Example:

/**
 * @type {import('nextra-theme-docs').DocsThemeConfig}
 */
export default {
  titleSuffix: '– Nextra'
}

nextLinks and prevLinks

Specifies if arrows are being shown at the bottom of a page showing the next and previous page, like the ones at the bottom of this page.

Type: boolean

Default: true

Example:

/**
 * @type {import('nextra-theme-docs').DocsThemeConfig}
 */
export default {
  nextLinks: true,
  prevLinks: true
}

search

Specifies if a search box should be shown in the top right.

Type: boolean

Default: true

Example:

/**
 * @type {import('nextra-theme-docs').DocsThemeConfig}
 */
export default {
  search: true
}

searchPlaceholder

Specifies if a search box should be shown in the top right.

Type: string | ((props: { locale?: string }) => string){:ts}

Example:

/**
 * @type {import('nextra-theme-docs').DocsThemeConfig}
 */
export default {
  searchPlaceholder: ({ locale }) => {
    if (locale === 'zh-CN') return '搜索文档...'
    return 'Search documentation...'
  }
}

customSearch

A custom component to display instead of the search bar in the top right, for example Algolia.

Type: ReactNode

Example:

import Search from 'your-search'
/**
 * @type {import('nextra-theme-docs').DocsThemeConfig}
 */
export default {
  customSearch: <Search />
}

darkMode

Specifies if the user can select a dark mode.

Type: boolean

Default: true

Example:

/**
 * @type {import('nextra-theme-docs').DocsThemeConfig}
 */
export default {
  darkMode: true
}

defaultMenuCollapsed

Specifies if the menu on the left is collapsed by default.

Type: boolean

Default: false

Example:

/**
 * @type {import('nextra-theme-docs').DocsThemeConfig}
 */
export default {
  defaultMenuCollapsed: false
}

footer

Specifies if the footer should be shown.

Type: boolean

Default: true

Example:

/**
 * @type {import('nextra-theme-docs').DocsThemeConfig}
 */
export default {
  footer: true
}

footerText

The text that is shown on the left of the footer.

Type: ReactNode | React.FC<{ locale?: string }>{:ts}

Example:

/**
 * @type {import('nextra-theme-docs').DocsThemeConfig}
 */
export default {
  footerText: ({ locale }) => <>MIT ${new Date().getFullYear()} © Nextra.</>
}

footerEditLink

The components that should be shown on the link that leads to the editable page on the repository.

Type: ReactNode | React.FC<{ locale?: string }>{:ts}

Default: Edit this page

Example:

/**
 * @type {import('nextra-theme-docs').DocsThemeConfig}
 */
export default {
  footerEditLink: ({ locale }) => <>Edit this page on GitHub</>
}

feedbackLink

The components that should be shown on the link that leads to the issues or discussions of the repository.

Type: ReactNode | React.FC<{ locale?: string }>{:ts}

Default: ``

Example:

/**
 * @type {import('nextra-theme-docs').DocsThemeConfig}
 */
export default {
  feedbackLink: ({ locale }) => <>Question? Give us feedback →</>
}

feedbackLabels

Label used for create issue or discussion.

Type: string

Default: ``

Example:

/**
 * @type {import('nextra-theme-docs').DocsThemeConfig}
 */
export default {
  feedbackLabels: 'feedbacks'
}

logo

The logo in the top left.

Type: ReactNode | React.FC<{ locale?: string }>{:ts}

Example:

/**
 * @type {import('nextra-theme-docs').DocsThemeConfig}
 */
export default {
  logo: ({ locale }) => (
    <>
      <span className="mr-2 font-extrabold hidden md:inline">Nextra</span>
      <span className="text-gray-600 font-normal hidden md:inline">
        The Next Docs Builder
      </span>
    </>
  )
}

head

The head that should be inserted into the html document.

Type: ReactNode | React.FC<{ locale?: string; config: DocsThemeConfig; title: string; meta: Record<string, any> }>{:ts}

Example:

/**
 * @type {import('nextra-theme-docs').DocsThemeConfig}
 */
export default {
  head: ({ locale, title, config, meta }) => (
    <>
      <meta name="msapplication-TileColor" content="#ffffff" />
      <meta name="theme-color" content="#ffffff" />
      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
      <meta httpEquiv="Content-Language" content="en" />
      <meta name="description" content="Nextra: the next docs builder" />
      <meta name="twitter:card" content="summary_large_image" />
      <meta name="twitter:site" content="@shuding_" />
      <meta property="og:title" content="Nextra: the next docs builder" />
      <meta property="og:description" content="Nextra: the next docs builder" />
      <meta name="apple-mobile-web-app-title" content="Nextra" />
    </>
  )
}

direction

The direction of the text on the page

Type: 'ltr' | 'rtl'

Default: 'ltr'

Example:

/**
 * @type {import('nextra-theme-docs').DocsThemeConfig}
 */
export default {
  direction: 'ltr'
}

floatTOC

Specifies if the table of conents of a page (the headings) should be displayed floating on the right instead of being integrated in the menu on the left.

Type: boolean

Default: false

Example:

/**
 * @type {import('nextra-theme-docs').DocsThemeConfig}
 */
export default {
  floatTOC: false
}

projectChatLink

The URL that the chat button in the top right will point to.

Type: string

Example:

/**
 * @type {import('nextra-theme-docs').DocsThemeConfig}
 */
export default {
  projectChatLink: 'https://discord.gg/hEM84NMkRv'
}

projectChatLinkIcon

The icon component that is used as the chat button

Type: ReactNode

Example:

/**
 * @type {import('nextra-theme-docs').DocsThemeConfig}
 */
export default {
  projectChatLinkIcon: <Discord />
}

banner

The banner content that will display at top of the page.

Type: ReactNode | React.FC<{ locale?: string }>{:ts}

Example:

/**
 * @type {import('nextra-theme-docs').DocsThemeConfig}
 */
export default {
  banner: ({ locale }) => 'Nextra 2'
}

bannerKey

The key that is used to control the display of banner in localStorage.

Type: string

Default: 'nextra-banner'

Example:

/**
 * @type {import('nextra-theme-docs').DocsThemeConfig}
 */
export default {
  bannerKey: 'Nextra-banner'
}

gitTimestamp

The component that is used to display timestamp of the last commit of current page.

Type: string | React.FC<{ locale?: string; timestamp: Date }>{:ts}

Example:

/**
 * @type {import('nextra-theme-docs').DocsThemeConfig}
 */
export default {
  gitTimestamp: 'Last updated on'
}

tocExtraContent

The extra content that is displayed under the table of contents.

Type: ReactNode | React.FC<unknown>{:ts}

Example:

/**
 * @type {import('nextra-theme-docs').DocsThemeConfig}
 */
export default {
  tocExtraContent: () => {
    return <img src="http://placekitten.com/g/300/200" />
  }
}

i18n

The internationalization (i18n) config. See more here.

unstable_faviconGlyph

A glyph that should be used as a favicon.

Type: char

Example:

/**
 * @type {import('nextra-theme-docs').DocsThemeConfig}
 */
export default {
  unstable_faviconGlyph: '🐱'
}

unstable_flexsearch

Enable Nextra built-in search

Type: boolean | { codeblock: boolean }

Example:

const withNextra = require('nextra')({
  theme: 'nextra-theme-blog',
  themeConfig: './theme.config.js'
  unstable_flexsearch: {
    codeblock: false
  }
})
module.exports = withNextra()

unstable_searchResultEmpty

Empty component for search result.

Type: boolean | { codeblock: boolean }

Example:

/**
 * @type {import('nextra-theme-docs').DocsThemeConfig}
 */
export default {
  unstable_searchResultEmpty: ({ locale }) => {
    if (locale === 'zh-CN') return <span> 未查找到结果 </span>
    return <span> No results found. </span>
  }
}