From 94ef0b3b3199b8208d3908674f43807101eea7ae Mon Sep 17 00:00:00 2001 From: Shu Ding Date: Thu, 1 Dec 2022 15:42:37 +0100 Subject: [PATCH] Improve 2.0 docs (#989) * improve docs * add changeset --- .changeset/angry-scissors-applaud.md | 7 + docs/pages/_meta.json | 16 +- docs/pages/about.mdx | 28 +++ docs/pages/docs/_meta.json | 7 +- docs/pages/docs/about.mdx | 24 --- docs/pages/docs/blog-theme.mdx | 11 +- docs/pages/docs/blog-theme/start.mdx | 84 +++++---- docs/pages/docs/custom-theme.mdx | 6 + docs/pages/docs/docs-theme/start.mdx | 2 +- .../docs/docs-theme/theme-configuration.mdx | 6 +- docs/pages/docs/guide.mdx | 6 + docs/pages/docs/guide/_meta.json | 2 +- docs/pages/docs/guide/advanced.mdx | 12 ++ docs/pages/docs/guide/advanced/_meta.json | 4 +- .../docs/guide/advanced/code-highlighting.mdx | 11 -- docs/pages/docs/guide/advanced/remote.mdx | 7 + docs/pages/docs/guide/advanced/table.mdx | 2 +- docs/pages/docs/guide/i18n.mdx | 8 +- docs/pages/docs/guide/link.mdx | 18 +- docs/pages/docs/guide/markdown.mdx | 26 +-- docs/pages/docs/guide/organize-files.mdx | 4 +- docs/pages/docs/guide/syntax-highlighting.mdx | 160 ++++++++++++++++++ docs/pages/docs/guide/typescript.mdx | 8 +- docs/pages/index.mdx | 16 +- docs/style.css | 3 +- docs/theme.config.tsx | 6 +- packages/nextra-theme-docs/src/constants.tsx | 7 +- 27 files changed, 363 insertions(+), 128 deletions(-) create mode 100644 .changeset/angry-scissors-applaud.md create mode 100644 docs/pages/about.mdx delete mode 100644 docs/pages/docs/about.mdx create mode 100644 docs/pages/docs/guide/advanced.mdx delete mode 100644 docs/pages/docs/guide/advanced/code-highlighting.mdx create mode 100644 docs/pages/docs/guide/syntax-highlighting.mdx diff --git a/.changeset/angry-scissors-applaud.md b/.changeset/angry-scissors-applaud.md new file mode 100644 index 0000000000..2af88a2514 --- /dev/null +++ b/.changeset/angry-scissors-applaud.md @@ -0,0 +1,7 @@ +--- +'nextra-theme-docs': patch +'nextra': patch +'nextra-theme-blog': patch +--- + +improve 2.0 docs diff --git a/docs/pages/_meta.json b/docs/pages/_meta.json index 27bf7daaa7..92352f2806 100644 --- a/docs/pages/_meta.json +++ b/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" } } } diff --git a/docs/pages/about.mdx b/docs/pages/about.mdx new file mode 100644 index 0000000000..10b5a0c499 --- /dev/null +++ b/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. diff --git a/docs/pages/docs/_meta.json b/docs/pages/docs/_meta.json index 941f902aec..29a9117910 100644 --- a/docs/pages/docs/_meta.json +++ b/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" } diff --git a/docs/pages/docs/about.mdx b/docs/pages/docs/about.mdx deleted file mode 100644 index 68475d194b..0000000000 --- a/docs/pages/docs/about.mdx +++ /dev/null @@ -1,24 +0,0 @@ -# About - -Nextra was created by [Shu Ding](https://twitter.com/shuding_) and [Paco Coursey](https://twitter.com/pacocoursey) in 2020. - -## Team - -// Maintainers and contributors - -## Credits - -On top of React, Nextra is inspired and/or built on top of these incredible open source projects: - -- https://nextjs.org -- https://pnpm.io -- https://turborepo.org -- https://github.com/pacocoursey/next-themes -- https://mdxjs.com -- 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 -- https://docusaurus.io -- https://vitepress.vuejs.org diff --git a/docs/pages/docs/blog-theme.mdx b/docs/pages/docs/blog-theme.mdx index d17eb27aa7..cecce9d99a 100644 --- a/docs/pages/docs/blog-theme.mdx +++ b/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' + + Docs for this theme is under construction. + + + +} title="Get Started" href="/docs/blog-theme/start"> + diff --git a/docs/pages/docs/blog-theme/start.mdx b/docs/pages/docs/blog-theme/start.mdx index 13ca554c92..9e94af2bb0 100644 --- a/docs/pages/docs/blog-theme/start.mdx +++ b/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' + + Docs for this theme is under construction. + - 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). -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` +
-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: + + + + ```bash + pnpm i next react react-dom nextra nextra-theme-blog + ``` + + + ```bash + npm i next react react-dom nextra nextra-theme-blog + ``` + + + ```bash + yarn add next react react-dom nextra nextra-theme-blog + ``` + + + + + If you already have Next.js installed in your project, you only need to install `nextra` and `nextra-theme-blog` as the add-ons. + + +### 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:

MIT 2022 © Nextra.

, @@ -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 -} -``` - -5. You are good to go! - ---- - - -You can also use [` @@ -289,18 +291,12 @@ export function I18n() {

Hybrid rendering,
next generation.

With Nextra, you can leverage the hybrid rendering power from Next.js with your Markdown content including [SSG](https://nextjs.org/docs/basic-features/pages#static-generation-recommended), [SSR](https://nextjs.org/docs/basic-features/pages#server-side-rendering), and [ISR](https://nextjs.org/docs/basic-features/data-fetching/incremental-static-regeneration).

- -

Optimized SEO

-

Nextra has [next-seo](https://github.com/garmeeh/next-seo) built in.

- - +

And more...

+

Nextra has [next-seo](https://github.com/garmeeh/next-seo) built in.

 +

Start Using Nextra →

- -
-

Documentation →

-
diff --git a/docs/style.css b/docs/style.css index e221277835..a960f05992 100644 --- a/docs/style.css +++ b/docs/style.css @@ -16,11 +16,12 @@ color: hsl(var(--nextra-primary-hue) 100% 50% / var(--tw-text-opacity)); } -figurecaption { +figcaption { font-size: 0.85rem; line-height: 1.5rem; display: block; text-align: center; + margin-top: 0.5rem; } code.text-\[\.9em\] { diff --git a/docs/theme.config.tsx b/docs/theme.config.tsx index 1634198344..da6245732f 100644 --- a/docs/theme.config.tsx +++ b/docs/theme.config.tsx @@ -94,7 +94,11 @@ const config: DocsThemeConfig = { // ) // }, editLink: { - text: 'Edit this page on GitHub' + text: 'Edit this page on GitHub →' + }, + feedback: { + content: () => <>Question? Give us feedback →, + labels: 'feedback' }, sidebar: { titleComponent: ({ title, type }) => { diff --git a/packages/nextra-theme-docs/src/constants.tsx b/packages/nextra-theme-docs/src/constants.tsx index 66dcb812a6..6d99829a44 100644 --- a/packages/nextra-theme-docs/src/constants.tsx +++ b/packages/nextra-theme-docs/src/constants.tsx @@ -42,7 +42,10 @@ export const DEFAULT_THEME: DocsThemeConfig = { }, text: 'Edit this page' }, - feedback: {}, + feedback: { + content: () => <>Question? Give us feedback →, + labels: 'feedback' + }, footer: { component: Footer, text: `MIT ${new Date().getFullYear()} © Nextra.` @@ -84,7 +87,7 @@ export const DEFAULT_THEME: DocsThemeConfig = { ), logoLink: true, navbar: { - component: Navbar, + component: Navbar }, navigation: true, nextThemes: {