From 8d0eefce1357862985066ed01fecb1a70ccc7f57 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=A9my?= Date: Wed, 9 Nov 2022 14:57:15 +0100 Subject: [PATCH 1/3] =?UTF-8?q?=F0=9F=93=9D=20add=20first=20kitchen=20docu?= =?UTF-8?q?mentation=20with=20a=20getting=20started=20part?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- components/Footer/index.tsx | 5 - pages/advanced/code-highlighting.mdx | 26 ---- pages/advanced/meta.json | 3 - pages/features/i18n.mdx | 44 ------ pages/features/image.mdx | 33 ---- pages/features/mdx.mdx | 162 -------------------- pages/features/meta.json | 7 - pages/features/ssg.mdx | 68 --------- pages/features/themes.mdx | 12 -- pages/get-started.mdx | 95 ------------ pages/meta.json | 7 +- pages/themes/blog/index.mdx | 75 --------- pages/themes/blog/meta.json | 3 - pages/themes/docs/bleed.mdx | 62 -------- pages/themes/docs/callout.mdx | 57 ------- pages/themes/docs/configuration.mdx | 221 --------------------------- pages/themes/docs/index.mdx | 15 -- pages/themes/docs/meta.json | 6 - pages/themes/meta.json | 4 - pages/tools/kitchen/get-started.mdx | 89 +++++++++++ pages/tools/kitchen/index.mdx | 21 +++ pages/tools/kitchen/meta.json | 4 + pages/tools/meta.json | 3 + styles/global.css | 8 +- theme.config.js | 4 +- 25 files changed, 122 insertions(+), 912 deletions(-) delete mode 100644 components/Footer/index.tsx delete mode 100644 pages/advanced/code-highlighting.mdx delete mode 100644 pages/advanced/meta.json delete mode 100644 pages/features/i18n.mdx delete mode 100644 pages/features/image.mdx delete mode 100644 pages/features/mdx.mdx delete mode 100644 pages/features/meta.json delete mode 100644 pages/features/ssg.mdx delete mode 100644 pages/features/themes.mdx delete mode 100644 pages/get-started.mdx delete mode 100644 pages/themes/blog/index.mdx delete mode 100644 pages/themes/blog/meta.json delete mode 100644 pages/themes/docs/bleed.mdx delete mode 100644 pages/themes/docs/callout.mdx delete mode 100644 pages/themes/docs/configuration.mdx delete mode 100644 pages/themes/docs/index.mdx delete mode 100644 pages/themes/docs/meta.json delete mode 100644 pages/themes/meta.json create mode 100644 pages/tools/kitchen/get-started.mdx create mode 100644 pages/tools/kitchen/index.mdx create mode 100644 pages/tools/kitchen/meta.json create mode 100644 pages/tools/meta.json diff --git a/components/Footer/index.tsx b/components/Footer/index.tsx deleted file mode 100644 index 20a0050..0000000 --- a/components/Footer/index.tsx +++ /dev/null @@ -1,5 +0,0 @@ -const Footer: React.FC = () => { - return <>© {new Date().getFullYear()} onRuntime Studio; -}; - -export default Footer; diff --git a/pages/advanced/code-highlighting.mdx b/pages/advanced/code-highlighting.mdx deleted file mode 100644 index e37f81e..0000000 --- a/pages/advanced/code-highlighting.mdx +++ /dev/null @@ -1,26 +0,0 @@ -# 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 deleted file mode 100644 index b3382bd..0000000 --- a/pages/advanced/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "code-highlighting": "Code Highlighting" -} \ No newline at end of file diff --git a/pages/features/i18n.mdx b/pages/features/i18n.mdx deleted file mode 100644 index 1a11f38..0000000 --- a/pages/features/i18n.mdx +++ /dev/null @@ -1,44 +0,0 @@ -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 deleted file mode 100644 index e6ca2f3..0000000 --- a/pages/features/image.mdx +++ /dev/null @@ -1,33 +0,0 @@ -# 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 deleted file mode 100644 index 04567b7..0000000 --- a/pages/features/mdx.mdx +++ /dev/null @@ -1,162 +0,0 @@ -# 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 deleted file mode 100644 index 369452f..0000000 --- a/pages/features/meta.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "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 deleted file mode 100644 index 736b975..0000000 --- a/pages/features/ssg.mdx +++ /dev/null @@ -1,68 +0,0 @@ -# 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 deleted file mode 100644 index 6a2e8cd..0000000 --- a/pages/features/themes.mdx +++ /dev/null @@ -1,12 +0,0 @@ -# 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 deleted file mode 100644 index b234172..0000000 --- a/pages/get-started.mdx +++ /dev/null @@ -1,95 +0,0 @@ -# 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.config.js` file: - -```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 [`