diff --git a/package.json b/package.json index d5214a8..43523af 100644 --- a/package.json +++ b/package.json @@ -20,6 +20,8 @@ }, "dependencies": { "next": "^12.1.5", + "nextra": "^1.1.0", + "nextra-theme-docs": "^1.2.6", "react": "^18.0.0", "react-dom": "^18.0.0" }, diff --git a/pages/_app.tsx b/pages/_app.tsx new file mode 100644 index 0000000..29ba221 --- /dev/null +++ b/pages/_app.tsx @@ -0,0 +1,6 @@ +import { AppProps } from "next/app"; +import "nextra-theme-docs/style.css"; + +export default function Nextra ({ Component, pageProps }: AppProps) { + return ; +} diff --git a/pages/advanced/code-highlighting.mdx b/pages/advanced/code-highlighting.mdx new file mode 100644 index 0000000..e37f81e --- /dev/null +++ b/pages/advanced/code-highlighting.mdx @@ -0,0 +1,26 @@ +# Code Highlighting + +`nextra-theme-docs` uses [Prism](https://prismjs.com) and [prism-react-renderer](https://github.com/FormidableLabs/prism-react-renderer) +to highlight the code blocks. This section covers how you can customize it. + +## More Languages + +To keep the bundle small, only a [subset of languages](https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/vendor/prism/includeLangs.js) +are included in the syntax highlighter. If you want to add more languages, you can do the following: + +1. Run `yarn add prismjs prism-react-renderer` to add dependencies to your Nextra project. +2. Add the following code to your `pages/_app.js`: + +```jsx +import Prism from 'prism-react-renderer/prism' + +(typeof global !== "undefined" ? global : window).Prism = Prism + +require("prismjs/components/prism-kotlin") +require("prismjs/components/prism-csharp") +``` + +Restart your app and you will have Kotlin and C# code highlighting supported. +You can find the full list of available languages [here](https://github.com/PrismJS/prism/tree/master/components). + +{/*## Custom Themes*/} diff --git a/pages/advanced/meta.json b/pages/advanced/meta.json new file mode 100644 index 0000000..b3382bd --- /dev/null +++ b/pages/advanced/meta.json @@ -0,0 +1,3 @@ +{ + "code-highlighting": "Code Highlighting" +} \ No newline at end of file diff --git a/src/pages/api/hello.ts b/pages/api/hello.ts similarity index 100% rename from src/pages/api/hello.ts rename to pages/api/hello.ts diff --git a/pages/features/i18n.mdx b/pages/features/i18n.mdx new file mode 100644 index 0000000..1a11f38 --- /dev/null +++ b/pages/features/i18n.mdx @@ -0,0 +1,44 @@ +import Callout from 'nextra-theme-docs/callout' + +# Next.js I18n + +This feature is only available in the docs theme. + +Nextra supports [Next.js Internationalized Routing](https://nextjs.org/docs/advanced-features/i18n-routing) out of the box. + +To add multi-language pages to your Nextra application, just need to config `i18n` in `next.config.js`: + +```js +// next.config.js +const withNextra = require('nextra')('nextra-theme-docs', './theme.config.js') +module.exports = withNextra({ + i18n: { + locales: ['en', 'zh', 'de'], + defaultLocale: 'en', + }, +}) +``` + +Then, add the locale codes to your file extensions (required for the default locale too): + +```plaintext +/pages + index.en.md + index.zh.md + index.de.md + meta.en.json + meta.zh.json + meta.de.json + ... +``` + +Finally, add the `i18n` option to your `theme.config.js` to configure the language dropdown: + +```jsx +i18n: [ + { locale: 'en', text: 'English' }, + { locale: 'zh', text: '中文' }, + { locale: 'de', text: 'Deutsch' }, + { locale: 'ar', text: 'العربية', direction: 'rtl' }, +] +``` diff --git a/pages/features/image.mdx b/pages/features/image.mdx new file mode 100644 index 0000000..e6ca2f3 --- /dev/null +++ b/pages/features/image.mdx @@ -0,0 +1,33 @@ +# Next.js Image + +You can use [Next.js Image](https://nextjs.org/docs/basic-features/image-optimization) directly in MDX. + +If the `demo.png` file is located at `/public/demo.png`, you can use the code below to display it: + +```markdown +import Image from 'next/image' + +Hello +``` + +## Static Image + +import Callout from 'nextra-theme-docs/callout' + + + You need to opt-in to this feature by enabling [`unstable_staticImage: + true`](/get-started#create-manually). + + +Nextra also supports automatic static image imports, you no longer need to specify the width and height of the image manually, +and you can directly use the Markdown syntax to display the same image: + +```markdown +![Hello](../../public/demo.png) +``` + +With Next.js Image, there will be no layout shift, and a beautiful blury placeholder will be shown by default when loading the images: + +
+ +![Nextra](../../public/og.png) diff --git a/pages/features/mdx.mdx b/pages/features/mdx.mdx new file mode 100644 index 0000000..04567b7 --- /dev/null +++ b/pages/features/mdx.mdx @@ -0,0 +1,162 @@ +# MDX + +With Nextra, all your `.md` and `.mdx` files under the pages directory will be rendered with [MDX](https://mdxjs.com/about), it's an +advanced Markdown format with React component support. + +You can use import and use React components inside your Markdown files like this: + +```markdown +import Callout from 'nextra-theme-docs/callout' + +**Markdown With React Components** + + + **MDX** (the library), at its core, transforms MDX (the syntax) to JSX. + It receives an MDX string and outputs a _JSX string_. It does this by parsing + the MDX document to a syntax tree and then generates a JSX document from that tree. + +``` + +Generates: + +import Callout from 'nextra-theme-docs/callout' + +
+**Markdown With React Components** + + + **MDX** (the library), at its core, transforms MDX (the syntax) to JSX. It + receives an MDX string and outputs a _JSX string_. It does this by parsing the + MDX document to a syntax tree and then generates a JSX document from that + tree. + +
+ +## Heading + +
+ +# **Hello**, This Is a _Title_ Inside `h1` + +

**Hello**, This Is a _Title_ Inside `h2`

+{/* using html tag to avoid being rendered in the sidebar */} + +### **Hello**, This Is a _Title_ Inside `h3` + +#### **Hello**, This Is a _Title_ Inside `h4` + +##### **Hello**, This Is a _Title_ Inside `h5` + +###### **Hello**, This Is a _Title_ Inside `h6` + +## List + +1. one +2. two +3. three + +- one +- two +- three + +## Task List + +```markdown +- [x] Write the press release +- [ ] Update the website +- [ ] Contact the media +``` + +Renders + +- [x] Write the press release +- [ ] Update the website +- [ ] Contact the media + +## Syntax Highlighting + +Automatic syntax highlighting: + +````markdown +```js +console.log('hello, world') +``` +```` + +Renders: + +```js +console.log('hello, world') +``` + +You can also add the `highlight=` modifier to highlight specific lines: + +````markdown +```jsx highlight=4,6-8 +import useSWR from 'swr' + +function Profile() { + const { data, error } = useSWR('/api/user', fetcher) + + if (error) return
failed to load
+ if (!data) return
loading...
+ return
hello {data.name}!
+} +``` +```` + +```jsx highlight=4,6-8 +import useSWR from 'swr' + +function Profile() { + const { data, error } = useSWR('/api/user', fetcher) + + if (error) return
failed to load
+ if (!data) return
loading...
+ return
hello {data.name}!
+} +``` + +## Inline Code + +You can use \`content\` to wrap inline code content like: `let x = 1`. + +## Blockquote + +> Where some people measure progress in answers-right per test or tests-passed per year, we are more interested in Sistine-Chapel-Ceilings per Lifetime. +> +> — Alan Kay, A Personal Computer for Children of All Ages + +Nested quotes: + +> > Where some people measure progress in answers-right per test or tests-passed per year, we are more interested in Sistine-Chapel-Ceilings per Lifetime. +> > +> > — Alan Kay, A Personal Computer for Children of All Ages +> +> This is **great**. +> +> — Shu Ding. + +## Table + +| Syntax | Description | Test Text | +| :------------ | :---------: | ----------: | +| Header | Title | Here's this | +| Paragraph | Text | And more | +| Strikethrough | | ~~Text~~ | + +## React Components + +React components and Markdown can be **mixed together**, for instance: + +```markdown +> +> Give [**Nextra**](https://github.com/shuding/nextra) a star! +> +``` + +Renders: + +> +> Give [**Nextra**](https://github.com/shuding/nextra) a star! +> diff --git a/pages/features/meta.json b/pages/features/meta.json new file mode 100644 index 0000000..369452f --- /dev/null +++ b/pages/features/meta.json @@ -0,0 +1,7 @@ +{ + "mdx": "MDX", + "ssg": "Next.js SSG", + "i18n": "Next.js i18n", + "image": "Next.js Image", + "themes": "Themes" +} diff --git a/pages/features/ssg.mdx b/pages/features/ssg.mdx new file mode 100644 index 0000000..736b975 --- /dev/null +++ b/pages/features/ssg.mdx @@ -0,0 +1,68 @@ +# Next.js SSG + +With Next.js, you can pre-render your page using [Static Generation (SSG)](https://nextjs.org/docs/basic-features/pages#static-generation-recommended). Your pages will be generated at build time and statically served to visitors. It can also be cached by a CDN to maximize the performance. + +This is supported by Nextra too. Here's an example: + +import { useSSG } from 'nextra/ssg' + +export const getStaticProps = ({ params }) => { + return fetch(`https://api.github.com/repos/shuding/nextra`) + .then((res) => res.json()) + .then((repo) => ({ + props: { + // We add an `ssg` field to the page props, + // which will be provided to the Nextra `useSSG` hook. + ssg: { + stars: repo.stargazers_count, + }, + }, + // The page will be considered as stale and regenerated every 60 seconds. + revalidate: 60, + })) +} + +export const Stars = () => { + // Get the data from SSG, and render it as a component. + const { stars } = useSSG() + return {stars} +} + +
+ Nextra has stars on GitHub! +
+ +The number above was generated at build time via `getStaticProps`. With [Incremental Static Regeneration](https://nextjs.org/docs/basic-features/data-fetching#incremental-static-regeneration) enabled, it will be kept up to date. + +--- + +Here's the MDX code for the example above: + +```js +import { useSSG } from 'nextra/ssg' + +export const getStaticProps = ({ params }) => { + return fetch(`https://api.github.com/repos/shuding/nextra`) + .then((res) => res.json()) + .then((repo) => ({ + props: { + // We add an `ssg` field to the page props, + // which will be provided to the Nextra `useSSG` hook. + ssg: { + stars: repo.stargazers_count, + }, + }, + // The page will be considered as stale and regenerated every 60 seconds. + revalidate: 60, + })) +} + +export const Stars = () => { + // Get the data from SSG, and render it as a component. + const { stars } = useSSG() + return {stars} +} + + +Nextra has stars on GitHub! +``` diff --git a/pages/features/themes.mdx b/pages/features/themes.mdx new file mode 100644 index 0000000..6a2e8cd --- /dev/null +++ b/pages/features/themes.mdx @@ -0,0 +1,12 @@ +# Themes + +Nextra itself is basically a plugin that normalizes your Markdown routes in Next.js into structural data, and it doesn't handle any styling related thing. A **theme** is what renders your actual pages, it works like a layout component in React. + +Nextra has 2 official themes that you can use: + +- [Docs Theme](/themes/docs) +- [Blog Theme](/themes/blog) + +You can also extend your own themes. Here's a great starter example by [@jaredpalmer](https://github.com/jaredpalmer): + +- [Nextra Blank Custom Theme/Boilerplate Example](https://github.com/jaredpalmer/nextra-blank-custom-theme) diff --git a/pages/get-started.mdx b/pages/get-started.mdx new file mode 100644 index 0000000..de7c548 --- /dev/null +++ b/pages/get-started.mdx @@ -0,0 +1,95 @@ +# Get Started + +## Quick Start with Vercel + +You can start by creating your own Nextra site and deploying to Vercel by clicking the link: + +[![](https://vercel.com/button)](https://vercel.com/new/clone?demo-description=Markdown%20powered%20docs%20site.%20Built%20with%20Next.js.&demo-image=https%3A%2F%2Fnextra.vercel.app%2Fdemo.png&demo-title=Documentation%20Starter%20Kit&demo-url=https%3A%2F%2Fnextra.vercel.app%2F&project-name=nextjs-docs&repository-name=nextjs-docs&s=https%3A%2F%2Fgithub.com%2Fshuding%2Fnextra&from=templates) + +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: `yarn add next nextra react react-dom` + +2. Install the docs theme (you can use any theme you like): `yarn add nextra-theme-docs` + +3. Create the following Next.js config: + +```jsx +// next.config.js +const withNextra = require('nextra')({ + theme: 'nextra-theme-docs', + 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: + +```jsx +// theme.config.js +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: ( + <> + ... + Next.js Static Site Generator + + ), + head: ( + <> + + + + + ), +} +``` + +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: + +```jsx +import 'nextra-theme-docs/style.css' + +export default function Nextra({ Component, pageProps }) { + return +} +``` + +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 [`