Improve 2.0 docs (#989)

* improve docs

* add changeset

.changeset/angry-scissors-applaud.md

@@ -0,0 +1,7 @@
+---
+'nextra-theme-docs': patch
+'nextra': patch
+'nextra-theme-blog': patch
+---
+
+improve 2.0 docs

docs/pages/_meta.json

@@ -15,17 +15,11 @@
     "title": "Showcase",
     "type": "page"
   },
-  "faq": {
-    "title": "FAQ",
-    "type": "menu",
-    "items": {
-      "about": {
-        "title": "About Nextra",
-        "href": "/docs/about"
-      },
-      "community": {
-        "title": "Community"
-      }
+  "about": {
+    "title": "About",
+    "type": "page",
+    "theme": {
+      "typesetting": "article"
     }
   }
 }

docs/pages/about.mdx

@@ -0,0 +1,28 @@
+# About
+
+Nextra was initially created by [Vercel](https://vercel.com) members [Shu Ding](https://twitter.com/shuding_) and [Paco Coursey](https://twitter.com/pacocoursey) in 2020. Since 2021, [Yixuan Xu](https://twitter.com/yixuanxu94) contributed tremendously to the project. In 2022, [Dimitri Postolov](https://twitter.com/dimitripost) from [The Guild](https://the-guild.dev) joined the core team to help with the development of 2.0.
+
+## Team
+
+Currently, the project is maintained by [Shu Ding](https://twitter.com/shuding_) and [Dimitri Postolov](https://twitter.com/dimitripost). You can check out the full list of contributors on [GitHub](https://github.com/shuding/nextra/graphs/contributors).
+
+## Credits
+
+Nextra is powered by these incredible open source projects:
+
+- https://reactjs.org
+- https://nextjs.org
+- https://turbo.build
+- https://mdxjs.com
+- https://pnpm.io
+- https://github.com/pacocoursey/next-themes
+- https://github.com/garmeeh/next-seo
+- https://github.com/shikijs/shiki
+- https://tailwindcss.com
+- https://github.com/nextapps-de/flexsearch
+- https://github.com/atomiks/rehype-pretty-code
+- https://github.com/Brooooooklyn/simple-git
+
+## License
+
+The Nextra project and themes are licensed under the MIT license.

docs/pages/docs/_meta.json

@@ -7,10 +7,5 @@
   },
   "docs-theme": "Docs Theme",
   "blog-theme": "Blog Theme",
-  "custom-theme": "Custom Theme",
-  "-- About --": {
-    "type": "separator",
-    "title": "About"
-  },
-  "about": "About"
+  "custom-theme": "Custom Theme"
 }

docs/pages/docs/blog-theme.mdx

@@ -1,6 +1,15 @@
+import { Card, Cards } from '@components/card'
+import { Callout } from 'nextra-theme-docs'
+
 # Nextra Blog Theme
 
-import { Card, Cards } from '@components/card'
+<Callout type="warning">
+  Docs for this theme is under construction.
+</Callout>
 
 <Cards>
+  <Card icon={<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor" className="w-6 h-6">
+  <path strokeLinecap="round" strokeLinejoin="round" d="M8.25 4.5l7.5 7.5-7.5 7.5" />
+</svg>} title="Get Started" href="/docs/blog-theme/start">
+  </Card>
 </Cards>

docs/pages/docs/blog-theme/start.mdx

@@ -1,31 +1,72 @@
+import { Callout, Tab, Tabs } from 'nextra-theme-docs'
+
 # Get Started
 
-import { Callout } from 'nextra-theme-docs'
+<Callout type="warning">
+  Docs for this theme is under construction.
+</Callout>
 
 <Callout>
-  An example of the blog theme can be found
-  [here](https://github.com/vercel-solutions/nextjs-portfolio-starter).
+  An example of the blog theme can be found [here](https://demo.vercel.blog).
 </Callout>
 
-Similar to the docs theme, you can install the blog theme with the following commands:
+Similar to the [Docs Theme](/docs/docs-theme/start), you can install the blog theme with the following commands:
+
+## Quick Start from Template
 
-### Configurations
 
-1. Install Next.js, Nextra and React: `yarn add next nextra react react-dom`
+## Start as New Project
 
-2. Install the blog theme: `yarn add nextra-theme-blog`
+<div className="steps-container">
 
-3. Create the following Next.js config and theme config under the root directory:
+### Install 
+
+To create a Nextra Docs site manually, you have to install **Next.js**, **React**, **Nextra**, and **Nextra Blog Theme**. In your project directory, run the following command to install the dependencies:
+
+<Tabs items={['pnpm', 'npm', 'yarn']}>
+  <Tab>
+    ```bash
+    pnpm i next react react-dom nextra nextra-theme-blog
+    ```
+  </Tab>
+  <Tab>
+    ```bash
+    npm i next react react-dom nextra nextra-theme-blog
+    ```
+  </Tab>
+  <Tab>
+    ```bash
+    yarn add next react react-dom nextra nextra-theme-blog
+    ```
+  </Tab>
+</Tabs>
+
+<Callout>
+  If you already have Next.js installed in your project, you only need to install `nextra` and `nextra-theme-blog` as the add-ons.
+</Callout>
+
+### Add Next.js Config
+
+Create the following `next.config.js` file in your project’s root directory:
 
 ```js filename="next.config.js"
 const withNextra = require('nextra')({
   theme: 'nextra-theme-blog',
-  themeConfig: './theme.config.jsx'
-  // optional: add `unstable_staticImage: true` to enable Nextra's auto image import
+  themeConfig: './theme.config.jsx',
 })
+
 module.exports = withNextra()
+
+// If you have other Next.js configurations, you can pass them as the parameter:
+// module.exports = withNextra({ /* other next.js config */ })
 ```
 
+With the above configuration, Nextra can handle Markdown files in your Next.js project, with the specified theme. Other Nextra configurations can be found in [Guide](/docs/guide).
+
+### Create Blog Theme Config
+
+Lastly, create the corresponding `theme.config.jsx` file in your project’s root directory. This will be used to configure the Nextra Blog theme:
+
 ```jsx filename="theme.config.jsx"
 export default {
   footer: <p>MIT 2022 © Nextra.</p>,
@@ -41,11 +82,6 @@ export default {
   readMore: 'Read More →',
   titleSuffix: null,
   postFooter: null,
-  cusdis: {
-    appId: 'your_app_id',
-    host: 'your_host(optional)',
-    lang: 'your_lang'
-  },
   darkMode: false,
   navs: [
     {
@@ -56,20 +92,8 @@ export default {
 }
 ```
 
-4. Create `pages/_app.jsx` and include the theme stylesheet:
+### Ready to Go!
 
-```jsx filename="_app.jsx"
-import 'nextra-theme-blog/style.css'
+Now, you can run the `pnpm next` command to start developing the project! 🎉
 
-export default function Nextra({ Component, pageProps }) {
-  return <Component {...pageProps} />
-}
-```
-
-5. You are good to go!
-
----
-
-<Callout>
-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.jsx`.
-</Callout>
+</div>

docs/pages/docs/custom-theme.mdx

@@ -1 +1,7 @@
 # Custom Theme
+
+import { Callout } from 'nextra-theme-docs'
+
+<Callout type="warning">
+  Docs for custom themes is under construction.
+</Callout>

docs/pages/docs/docs-theme/start.mdx

@@ -66,7 +66,7 @@ module.exports = withNextra()
 // module.exports = withNextra({ /* other next.js config */ })
 ```
 
-With the above configuration, Nextra can handle Markdown files in your Next.js project, with the specified theme. Full Nextra configurations can be found [here](/docs/docs-theme/theme-configuration).
+With the above configuration, Nextra can handle Markdown files in your Next.js project, with the specified theme. Other Nextra configurations can be found in [Guide](/docs/guide).
 
 ### Create Docs Theme Config
 

docs/pages/docs/docs-theme/theme-configuration.mdx

@@ -380,13 +380,15 @@ Show an “Edit this page” link on the page that points to the file URL on Git
 
 ### Feedback Link
 
-The built-in feedback link provides a way for users to submit feedback about the documentation. By default, it’s a link that points to the issue creation form of the docs repository, with the current website title prefilled.
+The built-in feedback link provides a way for users to submit feedback about the documentation. By default, it’s a link that points to the issue creation form of the docs repository, with the current website title prefilled: [example](https://github.com/shuding/nextra/issues/new?title=Feedback%20for%20%E2%80%9CTheme%20Configuration%E2%80%9D&labels=feedback).
 
 <OptionTable options={[
-  ['feedback.content', 'React.ReactNode | React.FC', 'Content of the feedback link.'],
+  ['feedback.content', 'React.ReactNode | React.FC | undefined', 'Content of the feedback button.'],
   ['feedback.labels', 'string', 'Labels that can be added to the new created GitHub issue.'],
 ]}/>
 
+To disable it, you can set `feedback.content` to `undefined`.
+
 ## End of Page
 
 ### Navigation

docs/pages/docs/guide.mdx

@@ -4,12 +4,18 @@ import { Card, Cards } from '@components/card'
 
 import markdownIcon from '@components/icons/markdown'
 
+The following features are configured via the Next.js configuration and are available in all themes.
+
 <Cards>
   <Card icon={<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor" className="w-6 h-6">
   <path strokeLinecap="round" strokeLinejoin="round" d="M15.75 17.25v3.375c0 .621-.504 1.125-1.125 1.125h-9.75a1.125 1.125 0 01-1.125-1.125V7.875c0-.621.504-1.125 1.125-1.125H6.75a9.06 9.06 0 011.5.124m7.5 10.376h3.375c.621 0 1.125-.504 1.125-1.125V11.25c0-4.46-3.243-8.161-7.5-8.876a9.06 9.06 0 00-1.5-.124H9.375c-.621 0-1.125.504-1.125 1.125v3.5m7.5 10.375H9.375a1.125 1.125 0 01-1.125-1.125v-9.25m12 6.625v-1.875a3.375 3.375 0 00-3.375-3.375h-1.5a1.125 1.125 0 01-1.125-1.125v-1.5a3.375 3.375 0 00-3.375-3.375H9.75" />
 </svg>
 } title="Organize Files" href="/docs/guide/organize-files"/>
   <Card icon={markdownIcon} title="Markdown" href="/docs/guide/markdown"/>
+  <Card icon={<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor" className="w-6 h-6">
+  <path strokeLinecap="round" strokeLinejoin="round" d="M9.813 15.904L9 18.75l-.813-2.846a4.5 4.5 0 00-3.09-3.09L2.25 12l2.846-.813a4.5 4.5 0 003.09-3.09L9 5.25l.813 2.846a4.5 4.5 0 003.09 3.09L15.75 12l-2.846.813a4.5 4.5 0 00-3.09 3.09zM18.259 8.715L18 9.75l-.259-1.035a3.375 3.375 0 00-2.455-2.456L14.25 6l1.036-.259a3.375 3.375 0 002.455-2.456L18 2.25l.259 1.035a3.375 3.375 0 002.456 2.456L21.75 6l-1.035.259a3.375 3.375 0 00-2.456 2.456zM16.894 20.567L16.5 21.75l-.394-1.183a2.25 2.25 0 00-1.423-1.423L13.5 18.75l1.183-.394a2.25 2.25 0 001.423-1.423l.394-1.183.394 1.183a2.25 2.25 0 001.423 1.423l1.183.394-1.183.394a2.25 2.25 0 00-1.423 1.423z" />
+</svg>
+} title="Syntax Highlighting" href="/docs/guide/syntax-highlighting"/>
   <Card icon={<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor" className="w-6 h-6">
   <path fillRule="evenodd" d="M14.615 1.595a.75.75 0 01.359.852L12.982 9.75h7.268a.75.75 0 01.548 1.262l-10.5 11.25a.75.75 0 01-1.272-.71l1.992-7.302H3.75a.75.75 0 01-.548-1.262l10.5-11.25a.75.75 0 01.913-.143z" clipRule="evenodd" />
 </svg>

docs/pages/docs/guide/_meta.json

@@ -1,11 +1,11 @@
 {
   "organize-files": "Organize Files",
   "markdown": "Markdown",
+  "syntax-highlighting": "Syntax Highlighting",
   "ssg": "Next.js SSG",
   "i18n": "Next.js I18n",
   "image": "Next.js Image",
   "link": "Next.js Link",
   "typescript": "TypeScript",
-  "cms": "CMS",
   "advanced": "Advanced"
 }

docs/pages/docs/guide/advanced.mdx

@@ -0,0 +1,12 @@
+# Advanced
+
+import { Card, Cards } from '@components/card'
+
+<Cards>
+  <Card icon={<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor" className="w-6 h-6">
+  <path strokeLinecap="round" strokeLinejoin="round" d="M3.375 19.5h17.25m-17.25 0a1.125 1.125 0 01-1.125-1.125M3.375 19.5h7.5c.621 0 1.125-.504 1.125-1.125m-9.75 0V5.625m0 12.75v-1.5c0-.621.504-1.125 1.125-1.125m18.375 2.625V5.625m0 12.75c0 .621-.504 1.125-1.125 1.125m1.125-1.125v-1.5c0-.621-.504-1.125-1.125-1.125m0 3.75h-7.5A1.125 1.125 0 0112 18.375m9.75-12.75c0-.621-.504-1.125-1.125-1.125H3.375c-.621 0-1.125.504-1.125 1.125m19.5 0v1.5c0 .621-.504 1.125-1.125 1.125M2.25 5.625v1.5c0 .621.504 1.125 1.125 1.125m0 0h17.25m-17.25 0h7.5c.621 0 1.125.504 1.125 1.125M3.375 8.25c-.621 0-1.125.504-1.125 1.125v1.5c0 .621.504 1.125 1.125 1.125m17.25-3.75h-7.5c-.621 0-1.125.504-1.125 1.125m8.625-1.125c.621 0 1.125.504 1.125 1.125v1.5c0 .621-.504 1.125-1.125 1.125m-17.25 0h7.5m-7.5 0c-.621 0-1.125.504-1.125 1.125v1.5c0 .621.504 1.125 1.125 1.125M12 10.875v-1.5m0 1.5c0 .621-.504 1.125-1.125 1.125M12 10.875c0 .621.504 1.125 1.125 1.125m-2.25 0c.621 0 1.125.504 1.125 1.125M13.125 12h7.5m-7.5 0c-.621 0-1.125.504-1.125 1.125M20.625 12c.621 0 1.125.504 1.125 1.125v1.5c0 .621-.504 1.125-1.125 1.125m-17.25 0h7.5M12 14.625v-1.5m0 1.5c0 .621-.504 1.125-1.125 1.125M12 14.625c0 .621.504 1.125 1.125 1.125m-2.25 0c.621 0 1.125.504 1.125 1.125m0 1.5v-1.5m0 0c0-.621.504-1.125 1.125-1.125m0 0h7.5" />
+</svg>} title="Rendering Tables" href="/docs/guide/advanced/table"/>
+  <Card icon={<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor" className="w-6 h-6">
+  <path strokeLinecap="round" strokeLinejoin="round" d="M2.25 15a4.5 4.5 0 004.5 4.5H18a3.75 3.75 0 001.332-7.257 3 3 0 00-3.758-3.848 5.25 5.25 0 00-10.233 2.33A4.502 4.502 0 002.25 15z" />
+</svg>} title="Remote Content" href="/docs/guide/advanced/remote"/>
+</Cards>

docs/pages/docs/guide/advanced/_meta.json

@@ -1,4 +1,4 @@
 {
-  "code-highlighting": "Code Highlighting",
-  "table": "Rendering Tables"
+  "table": "Rendering Tables",
+  "remote": "Remote Content"
 }

docs/pages/docs/guide/advanced/remote.mdx

@@ -0,0 +1,7 @@
+# Remote Content
+
+import { Callout } from 'nextra-theme-docs'
+
+<Callout emoji="🚨">
+  This page is a stub. Help us expand it by contributing!
+</Callout>

docs/pages/docs/guide/advanced/table.mdx

@@ -1,6 +1,6 @@
 import { Callout } from 'nextra-theme-docs'
 
-# Rendering Table
+# Rendering Tables
 
 ## GFM syntax
 

docs/pages/docs/guide/i18n.mdx

@@ -8,8 +8,12 @@ Nextra supports [Next.js Internationalized Routing](https://nextjs.org/docs/adva
 
 To add multi-language pages to your Nextra application, you need to config `i18n` in `next.config.js` first:
 
-```js filename="next.config.js"
-const withNextra = require('nextra')('nextra-theme-docs', './theme.config.jsx')
+```js filename="next.config.js" {7-10}
+const withNextra = require('nextra')({
+  theme: "nextra-theme-docs",
+  themeConfig: "./theme.config.tsx",
+})
+
 module.exports = withNextra({
   i18n: {
     locales: ['en', 'zh', 'de'],

docs/pages/docs/guide/link.mdx

@@ -1 +1,17 @@
-(todo)
+# Next.js Link
+
+All relative Markdown links are automatically converted to Next.js links. This means that the target page will be prefetched. And when you click on a link, the page will be loaded on the client-side like a SPA, without making a full page load. For example:
+
+```md
+Click [here](/about) to read more.
+```
+
+Will be equivalent to:
+
+```jsx
+import Link from 'next/link'
+
+Click <Link href="/about">here</Link> to read more.
+```
+
+This feature makes navigation between Nextra pages fast and seamless.