get-started.mdx

Get Started

Quick Start with Vercel

You can start by creating your own Nextra site and deploying to Vercel by clicking the link:

Vercel will create the Nextra repository and deploy the site for you with just a few clicks.
Once done, every change in the repository will be deployed automatically.

Create Manually

Nextra works like a Next.js plugin, and it accepts a theme config (layout) to render the page. To start:

1. Install Next.js, Nextra and React

<Nextra.Tabs items={['npm', 'yarn', 'pnpm']} defaultIndex={1}> <Nextra.Tab> bash npm i react react-dom next nextra </Nextra.Tab> <Nextra.Tab> bash yarn add react react-dom next nextra </Nextra.Tab> <Nextra.Tab> bash pnpm i react react-dom next nextra </Nextra.Tab> </Nextra.Tabs>

2. Install the docs theme

<Nextra.Tabs items={['npm', 'yarn', 'pnpm']} defaultIndex={1}> <Nextra.Tab> bash npm i nextra-theme-docs </Nextra.Tab> <Nextra.Tab> bash yarn add nextra-theme-docs </Nextra.Tab> <Nextra.Tab> bash pnpm i nextra-theme-docs </Nextra.Tab> </Nextra.Tabs>

3. Create the following Next.js config and theme config under the root directory:

const withNextra = require('nextra')({
  theme: 'nextra-theme-blog',
  themeConfig: './theme.config.js'
  // optional: add `unstable_staticImage: true` to enable Nextra's auto image import
})
module.exports = withNextra()

4. Create a theme.config.js file for the docs theme:

/**
 * @type {import('nextra-theme-docs').DocsThemeConfig}
 */
export default {
  projectLink: 'https://github.com/shuding/nextra', // GitHub link in the navbar
  docsRepositoryBase: 'https://github.com/shuding/nextra/blob/master', // base URL for the docs repository
  titleSuffix: ' – Nextra',
  nextLinks: true,
  prevLinks: true,
  search: true,
  customSearch: null, // customizable, you can use algolia for example
  darkMode: true,
  footer: true,
  footerText: `MIT ${new Date().getFullYear()} © Shu Ding.`,
  footerEditLink: `Edit this page on GitHub`,
  logo: (
    <>
      <svg>...</svg>
      <span>Next.js Static Site Generator</span>
    </>
  ),
  head: (
    <>
      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
      <meta name="description" content="Nextra: the next docs builder" />
      <meta name="og:title" content="Nextra: the next docs builder" />
    </>
  )
}

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

More configuration options for the docs theme can be found [here](/themes/docs/configuration).

5. Create pages/_app.js and include the theme stylesheet:

import 'nextra-theme-docs/style.css'

export default function Nextra({ Component, pageProps }) {
  const getLayout = Component.getLayout || (page => page)
  return getLayout(<Component {...pageProps} />)
}

6. You are good to go! Run yarn next to start.

---

Any `.md` or `.mdx` file will turn into a doc page and be displayed in sidebar. You can also create a `meta.json` file to customize the page order and title.
Check the source code: https://github.com/shuding/nextra for more information. You can also use [`<style jsx>`](https://nextjs.org/docs/basic-features/built-in-css-support#css-in-js) to style elements inside `theme.config.js`.