Polish v2 docs (#993)

* polish docs * add changeset * fix lint errors * fix test
shuding · Dec 2, 2022 · 66712f0 · 66712f0
1 parent fde2ac2
commit 66712f0
Show file tree

Hide file tree

Showing 23 changed files with 278 additions and 143 deletions.
diff --git a/.changeset/gentle-clouds-wave.md b/.changeset/gentle-clouds-wave.md
@@ -0,0 +1,6 @@
+---
+'nextra': patch
+'nextra-theme-docs': patch
+---
+
+polish docs
diff --git a/docs/components/features/style.module.css b/docs/components/features/style.module.css
@@ -88,17 +88,49 @@
   font-feature-settings: initial;
 }
 
-@media screen and (max-width: 920px) {
+.feature :global(.show-on-mobile) {
+  display: none;
+}
+
+@media screen and (max-width: 1024px) {
+  .feature {
+    max-width: 80vw;
+    width: 100%;
+  }
+  .feature.large {
+    grid-column: span 1;
+  }
   .features {
-    grid-template-columns: repeat(2, 1fr);
+    grid-template-columns: 1fr;
+    grid-gap: 3em;
+    justify-items: center;
+  }
+  .feature h3 {
+    font-size: 28px;
+    font-size: min(28px, max(4vw, 22px));
+    text-align: center;
   }
 }
 
 @media screen and (max-width: 640px) {
+  .feature {
+    max-width: 460px;
+    width: 100%;
+  }
   .feature.large {
     grid-column: span 1;
   }
   .features {
     grid-template-columns: 1fr;
+    grid-gap: 3em;
+    justify-items: center;
+  }
+  .feature h3 {
+    font-size: 34px;
+    font-size: min(34px, max(4vw, 22px));
+    text-align: center;
+  }
+  .feature :global(.show-on-mobile) {
+    display: block;
   }
 }
diff --git a/docs/next.config.mjs b/docs/next.config.mjs
@@ -3,11 +3,11 @@ import nextra from 'nextra'
 const withNextra = nextra({
   theme: 'nextra-theme-docs',
   themeConfig: './theme.config.tsx',
-  unstable_staticImage: true,
-  unstable_flexsearch: {
-    codeblocks: true
+  staticImage: true,
+  flexsearch: {
+    codeblocks: false
   },
-  unstable_defaultShowCopyCode: true
+  defaultShowCopyCode: true
 })
 
 export default withNextra({

diff --git a/docs/package.json b/docs/package.json
@@ -12,8 +12,8 @@
     "clsx": "^1.2.1",
     "framer-motion": "^7.3.2",
     "next": "^13.0.5",
-    "nextra": "2.0.0-beta.43",
-    "nextra-theme-docs": "2.0.0-beta.43",
+    "nextra": "2.0.0-beta.44",
+    "nextra-theme-docs": "2.0.0-beta.44",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"
   },

diff --git a/docs/pages/about.mdx b/docs/pages/about.mdx
@@ -1,4 +1,4 @@
-# About
+# About Nextra
 
 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.
 

diff --git a/docs/pages/docs/_meta.json b/docs/pages/docs/_meta.json
@@ -7,5 +7,13 @@
   },
   "docs-theme": "Docs Theme",
   "blog-theme": "Blog Theme",
-  "custom-theme": "Custom Theme"
+  "custom-theme": "Custom Theme",
+  "-- About --": {
+    "type": "separator",
+    "title": "More"
+  },
+  "about link": {
+    "title": "About Nextra",
+    "href": "/about"
+  }
 }
diff --git a/docs/pages/docs/blog-theme/start.mdx b/docs/pages/docs/blog-theme/start.mdx
@@ -80,7 +80,6 @@ export default {
     </>
   ),
   readMore: 'Read More →',
-  titleSuffix: null,
   postFooter: null,
   darkMode: false,
   navs: [

diff --git a/docs/pages/docs/docs-theme/start.mdx b/docs/pages/docs/docs-theme/start.mdx
@@ -78,7 +78,6 @@ export default {
   project: {
     link: 'https://github.com/shuding/nextra',
   },
-  titleSuffix: ' – Nextra',
   // ...
 }
 ```

diff --git a/docs/pages/docs/docs-theme/theme-configuration.mdx b/docs/pages/docs/docs-theme/theme-configuration.mdx
@@ -10,7 +10,6 @@ export default {
     link: 'https://github.com/shuding/nextra',
   },
   logo: <strong>Project</strong>,
-  titleSuffix: ' – Project',
 }
 ```
 
@@ -40,21 +39,46 @@ export default {
 
 Then Nextra will automatically generate the correct file path for all pages.
 
-### Title Suffix
+### SEO Options
 
-In Nextra, the website title will be the content of `<h1>` of each page. If `<h1>` is missing, it will use the page title specified in the [page configuration](/docs/docs-theme/page-configuration). You can also provide a global suffix via the `titleSuffix` option.
+You can configure SEO related settings via the `useNextSeoProps` option. The `useNextSeoProps` function returns the props that will be passed to the [Next SEO](https://github.com/garmeeh/next-seo#add-seo-to-page) component. 
+
+It is also a hook so you can use APIs like `useRouter` inside to return values conditionally.
 
 <OptionTable options={[
-  ['titleSuffix', 'string | (() => string)', 'The title suffix.'],
+  ['useNextSeoProps', '(() => NextSeoProps)', 'A React hook function that returns options for Next SEO.'],
 ]}/>
 
+For example, we can have all pages rendering the same suffix for `<title>`:
+
 import titleSuffixImage from '../../../public/assets/docs/title-suffix.png'
 
-<Screenshot src={titleSuffixImage} alt="Project link" />
+<Screenshot src={titleSuffixImage} alt="Title suffix" />
 
 ```jsx
 export default {
-  titleSuffix: ' – SWR',
+  useNextSeoProps() {
+    return {
+      titleTemplate: '%s – SWR'
+    }
+  },
+}
+```
+
+The `%s` is a [placeholder](https://github.com/garmeeh/next-seo#title-template) that will be replaced by the page title.
+
+You can also return it conditionally to avoid adding the suffix to the homepage:
+
+```jsx
+export default {
+  useNextSeoProps() {
+    const { route } = useRouter()
+    if (route !== '/') {
+      return {
+        titleTemplate: '%s – SWR'
+      }
+    }
+  },
 }
 ```
 

diff --git a/docs/pages/docs/get-started.mdx.backup b/docs/pages/docs/get-started.mdx.backup
@@ -34,7 +34,6 @@ module.exports = withNextra()
 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,

diff --git a/docs/pages/docs/index.mdx b/docs/pages/docs/index.mdx
@@ -20,31 +20,9 @@ To start using Nextra, you need to select a theme first:
     image
     arrow
     title="Blog theme"
-    href="/docs-theme/installation">
+    href="/docs/blog-theme/start">
     <>![](/assets/blog-theme.png)</>
   </Card>
 </Cards>
 
 If you want to use Nextra without a preset theme, or build your own theme, you can follow the [Custom Theme](/docs/custom-theme) docs.
-
-<div className="hidden">
-## Catalog
-
-<details>
-  <summary>What’s the relationship between Next.js, Nextra and Nextra Themes?</summary>
-  **Next.js** is a general purpose framework for building all kinds of web applications
-  with React. **Nextra** is a Next.js plugin, which provides a complete solution
-  around Markdown (MDX) on top of Next.js. A **Nextra Theme** is basically a “layout
-  component” that determines how a Nextra page is rendered.
-</details>
-
-<details>
-  <summary>Can I use Nextra in my existing Next.js project?</summary>
-  Yes, (todo)
-</details>
-
-<details>
-  <summary>Can I use the docs theme but also create a blog?</summary>
-  Yes, (todo)
-</details>
-</div>