From d5ffc36d878bca2a46a82a4a1f28e5f3c3d08e82 Mon Sep 17 00:00:00 2001 From: Mihovil Ilakovac Date: Wed, 6 Mar 2024 17:40:46 +0100 Subject: [PATCH] Fixes docs typos (#178) --- doc-site/pages/$.mdx | 6 ++-- doc-site/pages/advanced-fs-routing$.mdx | 18 +++++------ doc-site/pages/examples/component-library$.md | 10 +++---- doc-site/pages/fs-routing$.mdx | 10 +++---- doc-site/pages/i18n$.mdx | 22 +++++++------- .../library-documentation-tools/index$.mdx | 16 +++++----- doc-site/pages/magic-import$_deprecate.mdx | 12 ++++---- doc-site/pages/official-theme$.mdx | 16 +++++----- doc-site/pages/page-data$.mdx | 16 +++++----- doc-site/pages/theme-customization$.mdx | 16 +++++----- doc-site/pages/upgrade-from-v2-to-v3$.mdx | 20 ++++++------- doc-site/pages/upgrade-from-v3-to-v4$.mdx | 30 +++++++++---------- doc-site/pages/upgrade-from-v4-to-v5$.mdx | 18 +++++------ 13 files changed, 105 insertions(+), 105 deletions(-) diff --git a/doc-site/pages/$.mdx b/doc-site/pages/$.mdx index f88ab5d4..d562882c 100644 --- a/doc-site/pages/$.mdx +++ b/doc-site/pages/$.mdx @@ -29,10 +29,10 @@ It provides many features that help developers **build a React App quickly**: - **Fantastic development experience**. Start the local development server in a blink, even when you have many pages. Hot module replacement works with React and Mdx, so you can get instant feedback when you edit your code. - **Filesystem based routing**. By following a [simple filesystem routing convention](/fs-routing), It is easy to create, locate and develop pages. You don't need to worry about routing configuration. For advanced users, you can [tell vite-pages how to find page files](/advanced-fs-routing), so that vite-pages can work with any project file structure. - **Support Mdx**. You can write content with either "normal React" or [Mdx](https://mdxjs.com/). Normal Reactjs is more flexible and composable. While Mdx is more readable and easier to edit. You can choose the proper format for your task. These formats can import each other like normal esModules. -- **Powerful [theme customization](/theme-customization)**. Vite-pages itself doesn't render any concrete DOM node. You can customize **anything** on the page with theme. It is easy to write a theme that is sharable and configurable. If you use typescript, the users of your theme will get type-check and intelliSense. +- **Powerful [theme customization](/theme-customization)**. Vite-pages itself doesn't render any concrete DOM node. You can customize **anything** on the page with a theme. It is easy to write a theme that is sharable and configurable. If you use typescript, the users of your theme will get type-check and intelliSense. - **Automatic code splitting based on pages**. Visitors don't need to download the whole app, they only load page data as needed. -- **Support static site generation out of the box**. By pre-rendering your app into HTML at buildtime, users can see the content before any JS is loaded. With this feature, you can [deploy your single page apps on GitHub Pages](https://github.com/vitejs/vite-plugin-react-pages/tree/main/doc-site)(which [doesn't natively support single page apps](https://www.google.com/search?q=github+pages+single+page+apps&oq=github+pages+single+page+apps)). -- **Tools for Library documentation**. Vite-pages provides [some tools](/library-documentation-tools) to reduce the maintenance costs for library authors and make their documents more easily to read. +- **Support static site generation out of the box**. By pre-rendering your app into HTML at build-time, users can see the content before any JS is loaded. With this feature, you can [deploy your single page apps on GitHub Pages](https://github.com/vitejs/vite-plugin-react-pages/tree/main/doc-site)(which [doesn't natively support single page apps](https://www.google.com/search?q=github+pages+single+page+apps&oq=github+pages+single+page+apps)). +- **Tools for Library documentation**. Vite-pages provides [some tools](/library-documentation-tools) to reduce the maintenance costs for library authors and make their documents easier to read. ## Getting stated diff --git a/doc-site/pages/advanced-fs-routing$.mdx b/doc-site/pages/advanced-fs-routing$.mdx index bccbaaa7..26a6c532 100644 --- a/doc-site/pages/advanced-fs-routing$.mdx +++ b/doc-site/pages/advanced-fs-routing$.mdx @@ -8,7 +8,7 @@ subGroup: advanced > The "Basic Filesystem Routing Convention" should satisfy most users' needs. **You probably don't need to read this advanced guide**. -For advanced users, vite-pages let you implement your own filesystem routing convention: you can **teach vite-pages how to collect page data from your project**. +For advanced users, vite-pages lets you implement your own filesystem routing convention: you can **teach vite-pages how to collect page data from your project**. When [configuring vite-plugin-react-pages](https://github.com/vitejs/vite-plugin-react-pages/blob/main/packages/create-project/template-lib/docs/vite.config.ts), you can pass the `pageStrategy` option. It should be an instance of `PageStrategy` class. Here is an example of customizing pageStrategy: @@ -19,19 +19,19 @@ vite.config.ts: syntax="ts" /> -With this custom pageStrategy, page files don't need to ends with `$`. Instead, they need to match the pattern `**/index.{md,mdx,js,jsx,ts,tsx}`. +With this custom pageStrategy, page files don't need to end with `$`. Instead, they need to match the pattern `**/index.{md,mdx,js,jsx,ts,tsx}`. > Checkout complete examples in [the custom-find-pages2 fixture](https://github.com/vitejs/vite-plugin-react-pages/blob/main/packages/playground/custom-find-pages2/vite.config.ts) or [the project scaffold](https://github.com/vitejs/vite-plugin-react-pages/blob/main/packages/create-project/template-lib/docs/vite.config.ts). ### Steps of customizing pageStrategy -As shown by the above example, here is the usual steps to customize pageStrategy: +As shown by the above example, here are the usual steps to customize pageStrategy: 1. Define a `findPages` function and pass it to `PageStrategy` constructor. 2. Inside the `findPages`, use `helpers.watchFiles(baseDir, glob, fileHandler)` to find the files that you need. - vite-pages will pass the glob(or glob array) to [chokidar](https://github.com/paulmillr/chokidar). vite-pages use chokidar to scan the fileSystem and watch for files. - - Whenever a file is scaned, added or updated, vite-pages will call the `fileHandler` with that file. When the file is deleted, vite-pages will automatically delete the related page data. -3. Inside the `fileHandler`, read the infomation from the `file` and register page data by calling `fileHandlerAPI.addPageData`. + - Whenever a file is scanned, added or updated, vite-pages will call the `fileHandler` with that file. When the file is deleted, vite-pages will automatically delete the related page data. +3. Inside the `fileHandler`, read the information from the `file` and register page data by calling `fileHandlerAPI.addPageData`. - There are two more helpers inside `fileHandlerAPI` that help you to update page data. We will introduce them in the following section. ### Handle file events and update page data @@ -51,7 +51,7 @@ The `fileHandlerAPI` contains a set of helpers that help you to update page data #### fileHandlerAPI.addPageData(dataPiece) -When you have extracted some [page data](/page-data) (which is called dataPiece) in the `fileHandler`, call `addPageData` to register the data. So that vite-pages will load the data into theme for rendering. +When you have extracted some [page data](/page-data) (which is called dataPiece) in the `fileHandler`, call `addPageData` to register the data. So that vite-pages will load the data into the theme for rendering. The dataPiece should conform to this interface: @@ -114,7 +114,7 @@ Checkout [the custom-find-pages fixture](https://github.com/vitejs/vite-plugin-r #### fileHandlerAPI.getStaticData(pageId) -Similar to the `fileHandlerAPI.getRuntimeData` API, you can use `fileHandlerAPI.getStaticData` to get the staticData of a certain page. And tou can read or mutate the properties of it: +Similar to the `fileHandlerAPI.getRuntimeData` API, you can use `fileHandlerAPI.getStaticData` to get the staticData of a certain page. And you can read or mutate the properties of it: ```ts const staticData = fileHandlerAPI.getStaticData(pageId) @@ -155,11 +155,11 @@ export class DefaultPageStrategy extends PageStrategy { #### Examples -For real-life examples of customizing pageStrategy, checkout ["Example: develop a component library"](/examples/component-library). +For real-life examples of customizing pageStrategy, check out ["Example: develop a component library"](/examples/component-library). #### Types -Here is the relavent types: +Here are the relavent types: Monorepo has more advantages when components are complex and tend to evolve independently. If we use a single package to publish all these components like the above example, all components share a version number. If we need to introduce a breaking change in a component, we have to bump the major version of the whole package. But with the monorepo we only need to bump the major version of that sub-package. Users will be more confident to upgrade. -In that case, we create a seperate package to run vite-pages, collecting all components and their demos. The project setup will look like this: +In that case, we create a separate package to run vite-pages, collecting all components and their demos. The project setup will look like this: ```text packages @@ -80,5 +80,5 @@ packages └── package.json ``` -Checkout the complete example in [the lib-monorepo scaffold](https://github.com/vitejs/vite-plugin-react-pages/blob/main/packages/create-project/template-lib-monorepo/packages/demos/vite.config.ts). +Check out the complete example in [the lib-monorepo scaffold](https://github.com/vitejs/vite-plugin-react-pages/blob/main/packages/create-project/template-lib-monorepo/packages/demos/vite.config.ts). You can initialize this project [with one command](/) (choose `lib-monorepo` template). diff --git a/doc-site/pages/fs-routing$.mdx b/doc-site/pages/fs-routing$.mdx index 509da82f..35b1d852 100644 --- a/doc-site/pages/fs-routing$.mdx +++ b/doc-site/pages/fs-routing$.mdx @@ -11,7 +11,7 @@ Vite-pages generates page routes based on your project file structure (filesyste The basic filesystem routing convention is very intuitive. It works out of the box and doesn't need any config. It should satisfy most users' needs. -**You can create a page by simply creating a file**: `page-name$.tsx`. Notice the `$` **at the end of the filename**. Vite-pages recognizes it and know it is a page entry. +**You can create a page by simply creating a file**: `page-name$.tsx`. Notice the `$` **at the end of the filename**. Vite-pages recognizes it and knows it is a page entry. If the filename is `index$.tsx`, the page route path will be the path of the directory. See examples below. @@ -30,12 +30,12 @@ If the filename is `index$.tsx`, the page route path will be the path of the dir | `dir-name/[id]/index$.tsx` (URL Paramater) | `/dir-name/:id` | | `dir-name/[id]/[id2]$.tsx` (URL Paramaters) | `/dir-name/:id/:id2` | -Theme can decide what to render when no page matches the url. Checkout [the theme doc](/theme-customization). +Theme can decide what to render when no page matches the URL. Check out [the theme doc](/theme-customization). -If a page path contains url paramaters, you can use [useParams](https://reactrouter.com/web/example/url-params) of `react-router-dom` to access the actual paramaters. +If a page path contains URL parameters, you can use [useParams](https://reactrouter.com/web/example/url-params) of `react-router-dom` to access the actual parameters. -Checkout [the basic fixture](https://github.com/vitejs/vite-plugin-react-pages/tree/main/packages/playground/basic/pages) for an example. +Check out [the basic fixture](https://github.com/vitejs/vite-plugin-react-pages/tree/main/packages/playground/basic/pages) for an example. ## Advanced Filesystem Routing -The "Basic Filesystem Routing Convention" should satisfy most users' needs. For advanced users, vite-pages let you implement your own filesystem routing convention: you can **teach vite-pages how to collect page data from your project**. Checkout [advanced fs routing](/advanced-fs-routing). +The "Basic Filesystem Routing Convention" should satisfy most users' needs. For advanced users, vite-pages lets you implement your own filesystem routing convention: you can **teach vite-pages how to collect page data from your project**. Checkout [advanced fs routing](/advanced-fs-routing). diff --git a/doc-site/pages/i18n$.mdx b/doc-site/pages/i18n$.mdx index cf7e86a3..c54063d3 100644 --- a/doc-site/pages/i18n$.mdx +++ b/doc-site/pages/i18n$.mdx @@ -6,7 +6,7 @@ subGroup: advanced # Internationalization -i18n support can be provided by theme. For example, [the official theme(vite-pages-theme-doc)](/official-theme) support i18n. This document shows how to create a multi-lingual site with it. +i18n support can be provided by theme. For example, [the official theme(vite-pages-theme-doc)](/official-theme) supports i18n. This document shows how to create a multi-lingual site with it. ## Define i18n metadata in the theme config @@ -78,17 +78,17 @@ interface LocalConfig { } ``` -With this i18n metadata, the theme can decide which locale to apply. For any specific page, it match its pagePath with each `LocalConfig.routePrefix`: +With this i18n metadata, the theme can decide which locale to apply. For any specific page, it matches its pagePath with each `LocalConfig.routePrefix`: -- If the pagePath match with a `LocalConfig.routePrefix`, this locale will apply to the page +- If the pagePath matches with a `LocalConfig.routePrefix`, this locale will apply to the page - If the pagePath doesn't match any routePrefix, the `I18nConfig.defaultLocale` will apply to the page With the example config above, page `/foo$.tsx` will have the locale keyed with `en`. Page `/zh/foo$.tsx` will have the locale keyed with `zh`. What does it mean when we say "the page P has locale L" (or "locale L applies to page P")? It means two things: -- Most site-level theme configs can decide their value based on the current applied locale. So that you can render `topNavs` and `sideNavs` with the correct language. -- In any React Component, you can get the current applied locale from `useThemeCtx()` so that you can decide which i18n translated message to render. +- Most site-level theme configs can decide their value based on the currently applied locale. So that you can render `topNavs` and `sideNavs` with the correct language. +- In any React Component, you can get the currently applied locale from `useThemeCtx()` so that you can decide which i18n translated message to render. We will talk about these techniques in the following sections. @@ -191,18 +191,18 @@ docs └─ baz.md ``` -Each page with default locale should have its translated version. For example, `/zh/foo$.md` should be the chinese-translated version of `/foo$.md`. +Each page with the default locale should have its translated version. For example, `/zh/foo$.md` should be the Chinese-translated version of `/foo$.md`. ### Markdown pages: translate them into each locale -Here is a markdown page for default locale (`/foo$.md`): +Here is a markdown page for the default locale (`/foo$.md`): ```md --- -title: This is the title written in default locale +title: This is the title written in the default locale --- -This is the markdown content written in default locale. +This is the markdown content written in the default locale. ``` Here is the translated markdown page (`/zh/foo$.md`): @@ -258,7 +258,7 @@ const messages = { export default Page ``` -When defining the page for other locale (`/zh/bar$.tsx`), you can **re-export the React Component**: +When defining the page for the other locale (`/zh/bar$.tsx`), you can **re-export the React Component**: ```tsx /** @@ -272,7 +272,7 @@ Notice that we reuse the same React Component for multiple locales. And we defin > When using i18n library like `react-intl`, and you need to wrap your App with some custom React Component, you can use `ThemeConfig.AppWrapper`. -### Get current locale in React Components or Hooks +### Get the current locale in React Components or Hooks ```tsx import { useThemeCtx } from 'vite-pages-theme-doc' diff --git a/doc-site/pages/library-documentation-tools/index$.mdx b/doc-site/pages/library-documentation-tools/index$.mdx index 2ba55715..5dffefc5 100644 --- a/doc-site/pages/library-documentation-tools/index$.mdx +++ b/doc-site/pages/library-documentation-tools/index$.mdx @@ -6,13 +6,13 @@ subGroup: advanced # Library Documentation Tools -Vite-pages provides some tools to reduce the maintenance costs for library authors and make their documents more easily to read. +Vite-pages provides some tools to reduce the maintenance costs for library authors and make their documents easier to read. > These tools are mostly for library authors. ## Demos -Demos (or stories) are the fixtures that you use when you are developing your library locally. +Demos (or stories) are the fixtures that you use when you are developing your library locally. Vite-pages allows you to render demos into your app (which can be the document of your library). Using this feature, vite-pages app can not only serve as your **local develop environment** (so that you can debug your demos and your libary code locally), but also the **document for your library** (so that the users of your library can see your demos and lean how to use it). The following markdown @@ -40,7 +40,7 @@ export default function Page() { ## Extract Type info from Typescript code -Vite-pages allows can help you to extract Typescript type info and render it. With this feature, you **no loger need to manually maintain API infomation in your documents**! You can reuse your interfaces (and comments in them) from your source code! This is very conveniently for API documentation. +Vite-pages can help you to extract Typescript type info and render it. With this feature, you **no longer need to manually maintain API information in your documents**! You can reuse your interfaces (and comments in them) from your source code! This is very convenient for API documentation. ### Render Interface @@ -58,7 +58,7 @@ will result in: ### Render Type Alias -Besides interface, TsInfo API also support type alias. +Besides interfaces, TsInfo API also supports type aliases. SomeObjectLiteralType (Object Literal): @@ -68,7 +68,7 @@ SomeComplexType (Complex Type): ### Using TsInfo API in JS files -In jsx page, You can import and render tsInfo like this: +In a JSX page, You can import and render tsInfo like this: ```tsx import tsInfoData from './types.ts?tsInfo=ButtonProps' @@ -81,7 +81,7 @@ export default function Page() { ## Render text from files -You can also render text from any files. So that these files can be both "code" and "documentation". +You can also render text from any file. So that these files can be both "code" and "documentation". The following markdown @@ -93,7 +93,7 @@ will result in: -In jsx page, You can render file text like this: +In a JSX page, You can render file text like this: ```tsx // https://vitejs.dev/guide/assets.html#importing-asset-as-string @@ -107,4 +107,4 @@ export default function Page() { ## Examples -You can checkout [template-lib](https://github.com/vitejs/vite-plugin-react-pages/blob/main/packages/create-project/template-lib/src/Button/README.md) as an example. (You can [view it online](https://stackblitz.com/fork/github/vitejs/vite-plugin-react-pages/tree/main/packages/create-project/template-lib?file=src%2FButton%2FREADME.md&terminal=dev) or [init this project locally](https://vitejs.github.io/vite-plugin-react-pages/)) +You can check out [template-lib](https://github.com/vitejs/vite-plugin-react-pages/blob/main/packages/create-project/template-lib/src/Button/README.md) as an example. (You can [view it online](https://stackblitz.com/fork/github/vitejs/vite-plugin-react-pages/tree/main/packages/create-project/template-lib?file=src%2FButton%2FREADME.md&terminal=dev) or [init this project locally](https://vitejs.github.io/vite-plugin-react-pages/)) diff --git a/doc-site/pages/magic-import$_deprecate.mdx b/doc-site/pages/magic-import$_deprecate.mdx index 9e80dd89..ac439815 100644 --- a/doc-site/pages/magic-import$_deprecate.mdx +++ b/doc-site/pages/magic-import$_deprecate.mdx @@ -5,15 +5,15 @@ order: 4 # Magic import -Vite-pages support "magic import". Magic import is **normal esModule import sytax** with **tailored path convention**. It enable users to import things with special behavior. Users can use it to do powerful things. +Vite-pages support "magic import". Magic import is **normal esModule import syntax** with **tailored path convention**. It enables users to import things with special behavior. Users can use it to do powerful things. -> If you are familiar with the webpack loader mechanism, you can easily guess how magic import works. +> If you are familiar with the Webpack loader mechanism, you can easily guess how magic import works. ## Analyze source code -When you are documenting for some JavaScript/Typescript library, you normally want to show some js/ts code to readers. This magic import help you load source code from a module. It is kind of like [raw-loader from webpack](https://webpack.js.org/loaders/raw-loader/). This is very useful for demo code displaying. +When you are documenting for some JavaScript/Typescript library, you normally want to show some js/ts code to readers. This magic import helps you load source code from a module. It is kind of like [raw-loader from webpack](https://webpack.js.org/loaders/raw-loader/). This is very useful for demo code displaying. -You can get the module tree analysis by importing the module with query `?analyzeSource`. +You can get the module tree analysis by importing the module with the query `?analyzeSource`. For example: @@ -48,7 +48,7 @@ Checkout the [analyze-source-code fixture](https://github.com/vitejs/vite-plugin ### Relative module dependencies -For relative module dependencies(.e.g `import util from './dir/util.ts'`), their source code will be collected into the analyze result, as shown by the previous example. +For relative module dependencies(.e.g `import util from './dir/util.ts'`), their source code will be collected into the analysis result, as shown by the previous example. Relative module import can be js, jsx, ts, tsx, css, sass, etc. @@ -56,7 +56,7 @@ Relative module import can be js, jsx, ts, tsx, css, sass, etc. For those dependencies from `node_modules` (.e.g `import React from 'react'`), this magic import will **not** load source code for them. Instead, the dependencies' versions are recorded, as shown by the previous example. -This magic import gets dependencies' versions by find `package.json` up from the importer, and find the package version from these `package.json` fields: +This magic import gets dependencies' versions by finding a `package.json` up from the importer, and finds the package version from these `package.json` fields: - `peerDependencies` - `devDependencies` diff --git a/doc-site/pages/official-theme$.mdx b/doc-site/pages/official-theme$.mdx index d7c38f85..91b50c4e 100644 --- a/doc-site/pages/official-theme$.mdx +++ b/doc-site/pages/official-theme$.mdx @@ -29,7 +29,7 @@ export default createTheme({ ## Auto side menu generation -Doc theme can generation a side menu automatically, based on the pages information. +Doc theme can generate a side menu automatically, based on the pages information. You can control the title/sorting/grouping of the side menu, by notating these [page static data](/page-data#static-data): @@ -55,7 +55,7 @@ For example, if your site has these pages: /references/error-codes/code2 ``` -Firstly, the theme will divide pages into `group`s based on the **first segment** of page path: +Firstly, the theme will divide pages into `group`s based on the **first segment** of the page path: ``` group /: @@ -78,11 +78,11 @@ group references: You can customize `group` in page static data. For example: ``` -Put this at top of a markdown page: +Put this at the top of a markdown page: --- group: references --- -Or put this at top of a tsx/jsx page: +Or put this at the top of a TSX/JSX page: /** * @group references */ @@ -115,10 +115,10 @@ group references: `subGroup` can also be customized in page static data, just like `group` does. -What is the meanings of `group` and `subGroup`? +What is the meaning of `group` and `subGroup`? -- `group` is a site isolation boundary: we only display **one** `group` at a time. If a user open a page in group `references`, he/she will **only see side menu items from that group**. He/She will not see menu items from `components` group. -- `subGroup` decide how the theme sort side menu items. All side menu items with same `subGroup` will be rendered adjacently. This document site is an example. +- `group` is a site isolation boundary: we only display **one** `group` at a time. If a user opens a page in the group `references`, he/she will **only see side menu items from that group**. He/She will not see menu items from `components` group. +- `subGroup` decides how the theme sorts the side menu items. All side menu items with the same `subGroup` will be rendered adjacently. This document site is an example. ## Theme configs @@ -128,6 +128,6 @@ The `createTheme` exported by `vite-pages-theme-doc` accepts [these options](htt ## Fully theme customization -If the basic theme doesn't satisfy your need, you can [create your own theme](/theme-customization). +If the basic theme doesn't satisfy your needs, you can [create your own theme](/theme-customization). > Contributions to [the theme](https://github.com/vitejs/vite-plugin-react-pages/tree/main/packages/theme-doc) are always welcomed. diff --git a/doc-site/pages/page-data$.mdx b/doc-site/pages/page-data$.mdx index a5b22b94..1a004f2c 100644 --- a/doc-site/pages/page-data$.mdx +++ b/doc-site/pages/page-data$.mdx @@ -5,7 +5,7 @@ order: 2 # Page data -**Essentially, vite-pages is a React app framework that collect your pages data and pass them to your theme.** So what kinds of data does it collect? +**Essentially, vite-pages is a React app framework that collects your pages' data and passes them to your theme.** So what kinds of data does it collect? Each page consists of two kinds of data: @@ -18,7 +18,7 @@ Both of these page data are passed to the theme so that it can render the app. ## Static data -Static data usually contains the matadata of a page. Static data of **all pages** is loaded **eagerly** when the app bootstrap, so that the theme can render a side menu or a search box with this infomation. +Static data usually contains the metadata of a page. Static data of **all pages** is loaded **eagerly** when the app bootstraps, so that the theme can render a side menu or a search box with this information. > You should try to keep the static data as small as possible. @@ -60,7 +60,7 @@ This will be collected as: Runtime page data is whatever value you export from a page file. It contains the actual content of the page. -Most themes(.e.g [the official theme](/official-theme)) ask users to `export default` a React component from each page file. But that is not a requirement from vite-pages core. We will talk about this later. +Most themes(e.g. [the official theme](/official-theme)) ask users to `export default` a React component from each page file. But that is not a requirement from vite-pages core. We will talk about this later. ## Difference @@ -69,7 +69,7 @@ Both static data and runtime data are passed to the theme, so the theme can use Difference: - Static data of **all pages** is loaded **eagerly** when the app bootstrap. So you should try to keep the static data small. -- Runtime data is loaded **lazily** when user navigate to that page. +- Runtime data is loaded **lazily** when a user navigates to that page. - The value type of static data is limited (string or simple object/array), while the value of runtime data can be any javascript value (.e.g a React component). ## How themes consume these data @@ -88,9 +88,9 @@ Here is the interface of a theme: ## Vite-pages core doesn't care what your page data looks like -Vite-pages itself doesn't care what the page data looks like. How to interpret the page data and render the view, is totally decided by [the theme](/theme-customization). Vite-pages just collect your pages data and pass them to the theme. This design make the vite-pages core more "simple" and make themes more powerful. +Vite-pages itself doesn't care what the page data looks like. How to interpret the page data and render the view, is totally decided by [the theme](/theme-customization). Vite-pages just collect your pages' data and pass them to the theme. This design makes the vite-pages core more "simple" and makes themes more powerful. -Most themes(.e.g [the official theme](/official-theme)) ask users to `export default` a React component from each page file. But that is not a requirement from vite-pages core. +Most themes(e.g. [the official theme](/official-theme)) ask users to `export default` a React component from each page file. But that is not a requirement from vite-pages core. ## Advanced topic: how vite-pages represent page data internally @@ -115,10 +115,10 @@ interface PagesData { ### Composed page data -You may wonder why runtimeData and staticData are maps and we use a `key` to index into them (instead of just one data for a page). This is because **vite-pages let users create a page with multiple data pieces that originate from multiple files.** +You may wonder why runtimeData and staticData are maps and we use a `key` to index into them (instead of just one data for a page). This is because **vite-pages lets users create a page with multiple data pieces that originate from multiple files.** > We use this feature in [the project scaffold](https://github.com/vitejs/vite-plugin-react-pages/blob/main/packages/create-project/template-lib/docs/vite.config.ts). We use it to display demos from multiple files in one page. You can init this sample project [with one command](/) (choose `lib` template). -Most filesystem routing mechanism out there assume that each page map to only one file. But vite-pages doesn't enforce that rule! This make page data more flexible and programable. +Most filesystem routing mechanisms out there assume that each page maps to only one file. But vite-pages doesn't enforce that rule! This makes page data more flexible and programable. Checkout [the advanced-fs-routing doc](/advanced-fs-routing) or ["Example: develop a component library"](/examples/component-library) to learn more about how to create a page with multiple data pieces that originate from multiple files. diff --git a/doc-site/pages/theme-customization$.mdx b/doc-site/pages/theme-customization$.mdx index 3a2f2908..cee1c6c2 100644 --- a/doc-site/pages/theme-customization$.mdx +++ b/doc-site/pages/theme-customization$.mdx @@ -6,11 +6,11 @@ subGroup: advanced # Theme customization -> This is an advance guide about how to make a theme by yourself. If there is already themes that meet your needs(.e.g [the official theme](/official-theme)), you don't need to read this guide now! +> This is an advanced guide about how to make a theme by yourself. If there are already themes that meet your needs(e.g. [the official theme](/official-theme)), you don't need to read this guide now! -Vite-pages itself doesn't render any concrete DOM node. Users can customize **anything** with a theme. That's why theme is so powerful. +Vite-pages itself doesn't render any concrete DOM node. Users can customize **anything** with a theme. That's why themes are so powerful. -To use a theme, users should export their theme from `_theme.tsx`. It should export a React compoent. It will be rendered by vite-pages core, and get useful info from props: +To use a theme, users should export their theme from `_theme.tsx`. It should export a React component. It will be rendered by vite-pages core, and get useful info from props: - All pages' static data - All runtime data that is already loaded @@ -28,15 +28,15 @@ This is probably [the simplest theme](https://github.com/vitejs/vite-plugin-reac > Here is a more useful theme: [vite-pages-theme-doc](https://github.com/vitejs/vite-plugin-react-pages/blob/main/packages/theme-doc/src/index.tsx). Learn more about it in [this guide](/official-theme). -You can customize every bits of UI with theme. Welcome to share your theme with a npm package! +You can customize every bit of UI with a theme. Welcome to share your theme with a npm package! ## Suggestions ### To theme providers: make your theme easier to use -We encourage theme providers to export your theme as **a config function** that receive user config and return a `Theme`. +We encourage theme providers to export your theme as **a config function** that receives the user config and returns a `Theme`. -For example, the theme provider can export theme like this: +For example, the theme provider can export a theme like this: ```tsx // The theme config function accepts navs config @@ -76,13 +76,13 @@ export default createTheme({ As you can see, the theme is easier to use because **theme consumers don't need to know about the `Theme` API of vite-pages**. They only need to know about `createTheme` API from the theme. Users should be talking to the theme, instead of talking directly to vite-pages framework. -For this reason, we encourage theme providers to export config function like the `createTheme` above. +For this reason, we encourage theme providers to export a config function like the `createTheme` above. > You can refer to [vite-pages-theme-doc](https://github.com/vitejs/vite-plugin-react-pages/blob/main/packages/theme-doc/src/index.tsx) #### Release the power of Typescript -The above example show another benefit for users: theme users can get Typescript type-check and intelliSense when they are configuring theme. This is because users are calling the theme config function, instead of "exporting some configs". +The above example shows another benefit for users: theme users can get Typescript type-check and intelliSense when they are configuring a theme. This is because users are calling the theme config function, instead of "exporting some configs". ## Share your theme! diff --git a/doc-site/pages/upgrade-from-v2-to-v3$.mdx b/doc-site/pages/upgrade-from-v2-to-v3$.mdx index c6930efe..975cfc5e 100644 --- a/doc-site/pages/upgrade-from-v2-to-v3$.mdx +++ b/doc-site/pages/upgrade-from-v2-to-v3$.mdx @@ -22,13 +22,13 @@ Upgrade these package versions: } ``` -Notice that you need to [migrate your app to vite v3](https://vitejs.dev/guide/migration.html) with this setup. +Notice that you need to [migrate your app to Vite v3](https://vitejs.dev/guide/migration.html) with this setup. It is very recommended to migrate `vite-pages-theme-basic` to [vite-pages-theme-doc](/official-theme). -### Stick with vite v2 +### Stick with Vite v2 -If you are not ready for vite v3 for some reason, you can stick with vite v2: +If you are not ready for Vite v3 for some reason, you can stick with Vite v2: ```json { @@ -42,13 +42,13 @@ If you are not ready for vite v3 for some reason, you can stick with vite v2: } ``` -Notice the version of `@vitejs/plugin-react` need to be changed together with `vite`. +Notice the version of `@vitejs/plugin-react` needs to be changed together with `vite`. -We also recommend you to migrate `vite-pages-theme-basic` to [vite-pages-theme-doc](/official-theme) with this setup (with vite v2). +We also recommend you migrate `vite-pages-theme-basic` to [vite-pages-theme-doc](/official-theme) with this setup (with Vite v2). -## Install peerDependencies for mdx +## Install peerDependencies for MDX -`vite-plugin-mdx` no longer install mdx-related peerDependencies for you. You should install them in your project: +`vite-plugin-mdx` no longer installs mdx-related peerDependencies for you. You should install them in your project: ```json { @@ -59,13 +59,13 @@ We also recommend you to migrate `vite-pages-theme-basic` to [vite-pages-theme-d } ``` -> [vite-plugin-mdx](https://github.com/brillout/vite-plugin-mdx) has been moved to a seperate repo. ([related issue](https://github.com/vitejs/vite-plugin-react-pages/issues/6)) +> [vite-plugin-mdx](https://github.com/brillout/vite-plugin-mdx) has been moved to a separate repo. ([related issue](https://github.com/vitejs/vite-plugin-react-pages/issues/6)) ## A Small update to theme API > **If you have only used the basic theme and haven't created a custom theme. You don't need to care about this API change.** -In `vite-plugin-react-pages@3.x`, vite-pages don't pass staticData to the theme component any more. You should use the hook `useStaticData` to get staticData. This API update is for less prop drilling and more efficient HMR update during dev. +In `vite-plugin-react-pages@3.x`, vite-pages don't pass staticData to the theme component anymore. You should use the hook `useStaticData` to get staticData. This API update is for less prop drilling and more efficient HMR update during dev. ```ts interface ThemeProps { @@ -95,4 +95,4 @@ In `vite-plugin-react-pages@3.x`, vite-pages use chokidar to scan the fileSystem > Thanks [Alec Larson](https://github.com/aleclarson) for the idea and initial implementation. -In order to handle the change from from the fileSystem, the "Advanced Filesystem Routing" API has changed from the `findPages` API to the `pageStrategy` API. Checkout [the advanced-fs-routing doc](/advanced-fs-routing) to learn about the latest API. +In order to handle the change from the fileSystem, the "Advanced Filesystem Routing" API has changed from the `findPages` API to the `pageStrategy` API. Checkout [the advanced-fs-routing doc](/advanced-fs-routing) to learn about the latest API. diff --git a/doc-site/pages/upgrade-from-v3-to-v4$.mdx b/doc-site/pages/upgrade-from-v3-to-v4$.mdx index 22d5ee23..82187bd5 100644 --- a/doc-site/pages/upgrade-from-v3-to-v4$.mdx +++ b/doc-site/pages/upgrade-from-v3-to-v4$.mdx @@ -6,7 +6,7 @@ subGroup: upgrade-guides # Upgrade from v3 to v4 -vite-pages v4 is released with following improvements: +vite-pages v4 is released with the following improvements: - Support [Vite v4](https://vitejs.dev/guide/migration.html). - Upgrade React to [18.x](https://reactjs.org/blog/2022/03/08/react-18-upgrade-guide.html). @@ -14,22 +14,22 @@ vite-pages v4 is released with following improvements: - Upgrade mdx to [2.x](https://mdxjs.com/migrating/v2/). - Upgrade antd to [5.x](https://ant.design/docs/react/migration-v5) (for vite-pages-theme-doc). - Support [Node.js ECMAScript modules](https://nodejs.org/api/esm.html). -- Support markdown outline (table of content). +- Support markdown outline (table of contents). - Support search. ![outline-and-search](./_assets/outline-and-search.jpg) -The following article will show you the migrate instructions. If you encounter problems, open an issue in the repo. Or checkout the [getting-stated templates](https://vitejs.github.io/vite-plugin-react-pages/#getting-stated) for reference. +The following article will show you the migration instructions. If you encounter problems, open an issue in the repo. Or check out the [getting-stated templates](https://vitejs.github.io/vite-plugin-react-pages/#getting-stated) for reference. ## Upstream libraries migration -Most upgrade work for upstream libraries is already done inside `vite-plugin-react-pages` and `vite-pages-theme-doc`. But some migration need to be done in userland, if you are using some old APIs that are dropped by these upstream libraries. For example, you can no longer use `` of `react-router`. Checkout the links above for the migration guides of upstream libraries. +Most upgrade work for upstream libraries is already done inside `vite-plugin-react-pages` and `vite-pages-theme-doc`. But some of the migration needs to be done in userland, if you are using some old APIs that are dropped by these upstream libraries. For example, you can no longer use `` of `react-router`. Check out the links above for the migration guides of upstream libraries. -We expect upstream libraries migration to be very easy for framwork users, unless you used many `react-router` v5-only APIs. +We expect upstream libraries migration to be very easy for framework users unless you used many `react-router` v5-only APIs. ## Remove vite-plugin-mdx -Since `vite-plugin-mdx` doesn't support mdx v2, vite-pages now includes a builtin mdx plugin. So you should remove the `vite-plugin-mdx` in vite-pages v5. +Since `vite-plugin-mdx` doesn't support mdx v2, vite-pages now includes a built-in MDX plugin. So you should remove the `vite-plugin-mdx` in vite-pages v5. Update `vite.config.ts`: @@ -48,12 +48,12 @@ export default defineConfig({ }) ``` -Notice that `pages()` now return an array of vite plugins(instead of return a plugin). But vite can understand that and apply every plugin in that array. So the invoke pattern of `vite-plugin-react-pages` looks exactly the same as before! You don't need to apply the new builtin mdx plugin manually. +Notice that `pages()` now returns an array of Vite plugins(instead of returning a plugin). But Vite can understand that and apply every plugin in that array. So the invoke pattern of `vite-plugin-react-pages` looks exactly the same as before! You don't need to apply the new built-in MDX plugin manually. Update `package.json`: - Remove `vite-plugin-mdx` and `@mdx-js/mdx`. -- You should upgrade `@mdx-js/react` to `^2.1.5`. It is a peerDependencies of mdx, so it should be installed by your vite project. +- You should upgrade `@mdx-js/react` to `^2.1.5`. It is a peerDependencies of mdx, so it should be installed by your Vite project. ```diff { @@ -68,19 +68,19 @@ Update `package.json`: ## MDX Comment Syntax Change -mdx v2 drops support for HTML comment syntax `` (actually it drops all HTML syntax), and [the document](https://mdxjs.com/docs/what-is-mdx/#markdown) recommends using jsx comment syntax instead: +MDX v2 drops support for HTML comment syntax `` (actually it drops all HTML syntax), and [the document](https://mdxjs.com/docs/what-is-mdx/#markdown) recommends using JSX comment syntax instead: > HTML syntax doesn’t work in MDX as it’s replaced by JSX. Instead of HTML comments, you can use JavaScript comments in braces: `{/* comment! */}`. -The author explain the reason behind this at [this rfc](https://github.com/mdx-js/mdx/issues/1042#issuecomment-622281752). The author hopes that the mdx syntax is only composed of markdown syntax + JSX syntax. The introduction of HTML syntax is not necessary and it would increase the mental burden. +The author explains the reason behind this at [this rfc](https://github.com/mdx-js/mdx/issues/1042#issuecomment-622281752). The author hopes that the MDX syntax is only composed of markdown syntax + JSX syntax. The introduction of HTML syntax is not necessary and it would increase the mental burden. -> Although many markdown parsers support HTML syntax, it is technically not the syntax of markdown itself. Those markdown parsers support it because markdown was not expressive enough in the past (without mdx). mdx has already solved the lack of expressiveness (via JSX syntax), so there is no need to support HTML syntax. +> Although many markdown parsers support HTML syntax, it is technically not the syntax of markdown itself. Those markdown parsers support it because markdown was not expressive enough in the past (without MDX). MDX has already solved the lack of expressiveness (via JSX syntax), so there is no need to support HTML syntax. -The removing of html comment syntax does bring some migration costs. You can quickly migrate it by regular search and replacement: `` replace to `{/*$0*/}`. +The removal of HTML comment syntax does bring some migration costs. You can quickly migrate it by regular search and replacement: `` replace to `{/*$0*/}`. ## Use Node.js ECMAScript modules -The Node.js community is quickly migrating from CommonJS to ECMAScript modules (esm). And we encourage you to run vite on the esm mode of Node.js. +The Node.js community is quickly migrating from CommonJS to ECMAScript modules (esm). And we encourage you to run Vite on the esm mode of Node.js. -How to enable esm for Node.js? Just add a `"type": "module"` field to the `package.json` of your vite project! +How to enable ESM for Node.js? Just add a `"type": "module"` field to the `package.json` of your Vite project! -> It is encouraged to have a dedicated `package.json` for your vite project. Your vite project should not share a `package.json` with the npm package that you are publishing (or the worspace package in the project root directory, if you are using monorepo). +> It is encouraged to have a dedicated `package.json` for your Vite project. Your Vite project should not share a `package.json` with the npm package that you are publishing (or the workspace package in the project root directory, if you are using monorepo). diff --git a/doc-site/pages/upgrade-from-v4-to-v5$.mdx b/doc-site/pages/upgrade-from-v4-to-v5$.mdx index 84e81054..9484b4ff 100644 --- a/doc-site/pages/upgrade-from-v4-to-v5$.mdx +++ b/doc-site/pages/upgrade-from-v4-to-v5$.mdx @@ -6,18 +6,18 @@ subGroup: upgrade-guides # Upgrade from v4 to v5 -vite-plugin-react-pages v5 is released with following improvements: +vite-plugin-react-pages v5 is released with the following improvements: -- Upgrade vite to [v5](https://vitejs.dev/guide/migration.html). -- Upgrade mdx to [v3](https://mdxjs.com/migrating/v3/). +- Upgrade Vite to [v5](https://vitejs.dev/guide/migration.html). +- Upgrade MDX to [v3](https://mdxjs.com/migrating/v3/). -Most migration is done inside this plugin. And our upstream libraries (vite and mdx) did't bring many significant breaking changes. So it should be **very easy** for our users to migrate! The following article will show you the migrate instructions. +Most migration is done inside this plugin. Our upstream libraries (Vite and MDX) didn't bring many significant breaking changes. So it should be **very easy** for our users to migrate! The following article will show you the migration instructions. -If you encounter problems, open an issue in the repo. Or checkout the [getting-stated templates](https://vitejs.github.io/vite-plugin-react-pages/#getting-stated) for working setup. +If you encounter problems, open an issue in the repo. Or check out the [getting-stated templates](https://vitejs.github.io/vite-plugin-react-pages/#getting-stated) for working setup. ## Upgrade Node.js to 18+ -As [vite v5](https://vitejs.dev/guide/migration.html) required, you should upgrade Node.js to 18+. +As [Vite v5](https://vitejs.dev/guide/migration.html) requires Node.js 18+, you should upgrade Node.js to 18+. ## Upgrade project dependencies @@ -39,7 +39,7 @@ Upgrade these package versions: ## Check Upstream libraries migration -Most migration is done inside this plugin. Although the upstream libraries (vite and mdx) did't bring many significant breaking changes for you, you should still take a look on their migration guides: +Most migration is done inside this plugin. Although the upstream libraries (Vite and MDX) didn't bring many significant breaking changes for you, you should still take a look at their migration guides: -- [vite v5](https://vitejs.dev/guide/migration.html) -- [mdx v3](https://mdxjs.com/migrating/v3/) +- [Vite v5](https://vitejs.dev/guide/migration.html) +- [MDX v3](https://mdxjs.com/migrating/v3/)