Skip to content

Commit

Permalink
Fixes docs typos (#178)
Browse files Browse the repository at this point in the history
  • Loading branch information
infomiho authored Mar 6, 2024
1 parent 016cf6f commit d5ffc36
Show file tree
Hide file tree
Showing 13 changed files with 105 additions and 105 deletions.
6 changes: 3 additions & 3 deletions doc-site/pages/$.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
18 changes: 9 additions & 9 deletions doc-site/pages/advanced-fs-routing$.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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
Expand All @@ -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:
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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:

<FileText
src="../../packages/react-pages/src/node/page-strategy/types.doc.ts"
Expand Down
10 changes: 5 additions & 5 deletions doc-site/pages/examples/component-library$.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ subGroup: advanced

This is an example of using "Advanced Filesystem Routing" inside a component library project.

Suppose you are developing a React component library. Your project have file structure like this:
Suppose you are developing a React component library. Your project will have a file structure like this:

```text
src
Expand All @@ -30,7 +30,7 @@ src
└── index.ts
```

You want to use vite as your local demo development environment (because it is blazingly fast). **How to collect all components and all demos from this project?** The file structure doesn't follow the [Basic Filesystem Routing Convention](/fs-routing).
You want to use Vite as your local demo development environment (because it is blazingly fast). **How to collect all components and all demos from this project?** The file structure doesn't follow the [Basic Filesystem Routing Convention](/fs-routing).

The answer: implement your own filesystem routing convention!

Expand All @@ -39,7 +39,7 @@ vite.config.ts:

We use `api.getRuntimeData(pageId)` and `api.getStaticData(pageId)` inside fileHandlers to get the pageData object. We can mutate the data object, and vite-pages will update its pages accordingly.

Checkout the complete example in [the library project scaffold](https://github.com/vitejs/vite-plugin-react-pages/blob/main/packages/create-project/template-lib/docs/vite.config.ts).
Check out the complete example in [the library project scaffold](https://github.com/vitejs/vite-plugin-react-pages/blob/main/packages/create-project/template-lib/docs/vite.config.ts).
You can initialize this project [with one command](/) (choose `lib` template).

## Monorepo
Expand All @@ -48,7 +48,7 @@ In some cases, we want to publish each component in their own packages.

> 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
Expand Down Expand Up @@ -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).
10 changes: 5 additions & 5 deletions doc-site/pages/fs-routing$.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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).
22 changes: 11 additions & 11 deletions doc-site/pages/i18n$.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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`):
Expand Down Expand Up @@ -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
/**
Expand All @@ -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'
Expand Down
Loading

0 comments on commit d5ffc36

Please sign in to comment.