From 8615a617872f479202d3c0371cabfb018b7d3243 Mon Sep 17 00:00:00 2001 From: sanyuan <494130947@qq.com> Date: Fri, 30 Sep 2022 11:37:28 +0800 Subject: [PATCH] feat: add zh docs --- docs/zh/api/config-basic.md | 23 +++++----- docs/zh/api/config-extension.md | 46 +++++++++---------- docs/zh/api/config-front-matter.md | 22 +++++----- docs/zh/api/config-theme.md | 68 +++++++++++++---------------- docs/zh/guide/conventional-route.md | 36 +++++++-------- docs/zh/guide/custom-page.md | 18 ++++---- docs/zh/guide/extension.md | 20 ++++----- docs/zh/guide/spa-mode.md | 16 +++---- docs/zh/guide/static-assets.mdx | 32 +++++++------- docs/zh/guide/use-mdx.mdx | 22 +++++----- 10 files changed, 145 insertions(+), 158 deletions(-) diff --git a/docs/zh/api/config-basic.md b/docs/zh/api/config-basic.md index 16278229..d508d609 100644 --- a/docs/zh/api/config-basic.md +++ b/docs/zh/api/config-basic.md @@ -1,13 +1,11 @@ -# Basic Config +# 基础配置 ## base - Type: `string` - Default: `/` -The base URL the site will be deployed at. You can set this to a subdirectory if you plan to deploy your site to a subdirectory of your domain. - -For example, if you plan to deploy your site to `https://foo.github.io/bar/`, then you should set `base` to `"/bar/"`: +部署基准路径。比如，如果你计划将你的站点部署到 `https://foo.github.io/bar/`，那么你应该将 `base` 设置为 `"/bar/"`： ```js import { defineConfig } from 'islandjs'; @@ -22,13 +20,13 @@ export default defineConfig({ - Type: `string` - Default: `"Island"` -The title of the site. This will be used as the title of the home page and the title of the HTML document. For example: +站点标题。这个参数将被用作 HTML 页面的标题。例如： ```js import { defineConfig } from 'islandjs'; export default defineConfig({ - title: 'my-site' + title: '我的站点' }); ``` @@ -37,13 +35,13 @@ export default defineConfig({ - Type: `string` - Default: `""` -The description of the site. This will be used as the description of the home page and the description of the HTML document. For example: +站点描述。这将用作 HTML 页面的描述。例如： ```js import { defineConfig } from 'islandjs'; export default defineConfig({ - description: 'This is my site.' + description: '这是我的站点' }); ``` @@ -52,7 +50,7 @@ export default defineConfig({ - Type: `string` - Default: `""` -The icon of the site. This will be used as the icon of the home page and the icon of the HTML document. For example: +站点图标。这个路径将用作 HTML 页面的图标路径。例如： ```js import { defineConfig } from 'islandjs'; @@ -62,19 +60,20 @@ export default defineConfig({ }); ``` -Then Island.js will find your icon in the `public` directory. +然后 Island.js 会在 `public` 目录中找到你的图标。 ## appearance - Type: `boolean` - Default: `true` -Whether to appear the dark mode/light mode toggle button. For example: +是否出现暗黑模式/白天模式切换按钮。比如： ```js import { defineConfig } from 'islandjs'; export default defineConfig({ + // 不出现这个按钮 appearance: false }); ``` @@ -84,7 +83,7 @@ export default defineConfig({ - Type: `string` - Default: `.island/dist` -The output directory for the built site. For example: +自定义构建站点的输出目录。比如: ```js import { defineConfig } from 'islandjs'; diff --git a/docs/zh/api/config-extension.md b/docs/zh/api/config-extension.md index 1caa8983..3bfad858 100644 --- a/docs/zh/api/config-extension.md +++ b/docs/zh/api/config-extension.md @@ -1,13 +1,13 @@ -# Extension Config +# 扩展配置 -The extension config means that how to configure the build tool(Vite), the conventional route, the markdown parser and so on. +扩展配置是指如何配置构建工具（Vite）、常规路由、markdown 解析器等。 ## vite - Type: `Object` - Default: `{}` -The custom config for [Vite](https://vitejs.dev/config/).And the config you passed in will be merged deeply with the default config of Vite. For example: +[Vite]的自定义配置（https://vitejs.dev/config/）。你传入的配置将与Vite的默认配置深度合并。例如： ```js import { defineConfig } from 'islandjs'; @@ -26,14 +26,14 @@ export default defineConfig({ - Type: `Object` -The conventional route custom config.The ability is implemented by a vite plugin.You can pass in the following options to customize the plugin behavior: +自定义路由自定义配置。该能力是通过一个 Vite 插件实现的。你可以传入以下选项来自定义插件的行为： ### route.include - Type: `string[]` - Default: `[]` -Add some extra files to the routing. By default, only the files in the root directory and all subdirectories will be included in the routing. If you want to add some extra files to the routing, you can use this option. For example: +在路由中添加一些额外的文件。默认情况下，只有根目录和所有子目录中的文件才会包含在路由中。如果你想在路由中添加一些额外的文件，你可以使用这个选项。例如： ```js import { defineConfig } from 'islandjs'; @@ -45,14 +45,14 @@ export default defineConfig({ }); ``` -> Notice: the string in the array supports glob pattern. +> 注意：数组中的字符串支持 glob 模式。 ### route.exclude - Type: `string[]` - Default: `[]` -Exclude some files from the routing. For example: +从路由中排除一些文件。例如： ```js import { defineConfig } from 'islandjs'; @@ -64,14 +64,14 @@ export default defineConfig({ }); ``` -> Notice: the string in the array supports glob pattern. +> 注意：数组中的字符串支持 glob 模式。 ### route.extensions - Type: `string[]` - Default: `[]` -The extensions of the files that will be included in the routing. By default, Island.js will include all the `'js','jsx','ts','tsx','md','mdx'` files in the routing. If you want to add some extra extensions, you can use this option. For example: +将包含在路由中的文件的扩展名。默认情况下，Island.js 会在路由中包含所有 `'js'、'jsx'、'ts'、'tsx'、'md'、'mdx' 文件。如果你想添加一些额外的扩展，你可以使用这个选项。例如： ```js import { defineConfig } from 'islandjs'; @@ -88,7 +88,7 @@ export default defineConfig({ - Type: `string` - Default: `` -The prefix of the filepath that will be converted to a route. For example: +将被转换为路由的文件路径的前缀。例如： ```js import { defineConfig } from 'islandjs'; @@ -100,13 +100,13 @@ export default defineConfig({ }); ``` -Then the filepath `pages/foo/bar.md` in root dir will be converted to the route `/foo/bar`. +比如根目录中的文件路径 `pages/foo/bar.md` 将被转换为路由 `/foo/bar`。 ### route.root - Type: `string` -The root dir of the routing. By default, the root dir is the param you specify in island cli command. If you want to change the root dir, you can use this option. For example: +路由的根目录。默认情况下，根目录是你在 island cli 命令中指定的参数。如果要更改根目录，可以使用此选项。例如： ```js import { defineConfig } from 'islandjs'; @@ -122,20 +122,20 @@ export default defineConfig({ - Type: `Object` -The options for remark and rehype plugins. +remark 和 rehype 插件的选项。 ### markdown.remarkPlugins - Type: `Array` - Default: `[]` -The remark plugins that will be used to parse markdown files. There are following plugins that will be used by default: +用于解析 markdown 文件的备注插件。默认情况下将使用以下插件： -- [remark-gfm](https://www.npmjs.com/package/remark-gfm): Parse common markdown syntaxes `GFM`(GitHub Flavored Markdown). -- [remark-frontmatter](https://www.npmjs.com/package/remark-frontmatter): Parse front matter info in markdown files. -- [remark-mdx-frontmatter](https://www.npmjs.com/package/remark-mdx-frontmatter): Parse front matter info in mdx files. +- [remark-gfm](https://www.npmjs.com/package/remark-gfm): 解析常用 markdown 语法 `GFM`(GitHub Flavored Markdown)。 +- [remark-frontmatter](https://www.npmjs.com/package/remark-frontmatter): 解析 Markdown 文件中的 Front Matter 信息。 +- [remark-mdx-frontmatter](https://www.npmjs.com/package/remark-mdx-frontmatter): 解析 MDX 文件中的 Front Matter 信息。 -You can also use this option to add some extra remark plugins. For example: +你还可以使用此选项添加一些额外的 remark 插件。例如： ```js import { defineConfig } from 'islandjs'; @@ -154,13 +154,13 @@ export default defineConfig({ - Type: `Array` - Default: `[]` -The rehype plugins that will be used to parse HTML. There are following plugins that will be used by default: +将用于解析 HTML 的 rehype 插件。默认情况下将使用以下插件： -- [rehype-autolink-headings](https://www.npmjs.com/package/rehype-autolink-headings): Add anchor to headings. -- [rehype-slug](https://www.npmjs.com/package/rehype-slug): Add id to headings. -- [rehype-external-links](https://www.npmjs.com/package/rehype-external-links): Add `target="_blank"` to external links. +- [rehype-autolink-headings](https://www.npmjs.com/package/rehype-autolink-headings): 向标题添加锚点(a 标签)。 +- [rehype-slug](https://www.npmjs.com/package/rehype-slug): 在标题中添加 id。 +- [rehype-external-links](https://www.npmjs.com/package/rehype-external-links): 将 `target="_blank"` 添加到外部链接。 -You can also use this option to add some extra rehype plugins. For example: +你还可以使用此选项添加一些额外的 rehype 插件。例如： ```js import { defineConfig } from 'islandjs'; diff --git a/docs/zh/api/config-front-matter.md b/docs/zh/api/config-front-matter.md index 9c597cf0..94560a86 100644 --- a/docs/zh/api/config-front-matter.md +++ b/docs/zh/api/config-front-matter.md @@ -1,14 +1,14 @@ -# Front Matter Config +# Front Matter 配置 ## title - Type: `string` -The title of the page. By default, the h1 title of the page will be used as the title of the HTML document. But if you want to use a different title, you can use the `title` front matter to specify the title of the page. For example: +页面的标题。默认情况下，页面的 h1 标题将用作 HTML 文档的标题。但是如果你想使用不同的标题，你可以使用 Front Matter 来指定页面的标题。例如： ```md --- -title: My Page +title: 我的主页 --- ``` @@ -16,11 +16,11 @@ title: My Page - Type: `string` -The custom description of the page. For example: +页面的自定义描述。例如： ```md --- -description: This is my page. +description: 这是我的主页 --- ``` @@ -29,7 +29,7 @@ description: This is my page. - Type: `'home' | 'doc' | 'api' | 'custom' | '404'` - Default: `'doc'` -The type of the page. By default, the page type is `'doc'`. But if you want to use a different page type, you can use the `pageType` front matter to specify the page type. For example: +页面的类型。默认情况下，页面类型为`doc`。但是如果你想使用不同的页面类型，你可以使用`pageType`前面的东西来指定页面类型。例如： ```md --- @@ -42,7 +42,7 @@ pageType: home - Type: `boolean` - Default: `false` -Enable api page.It's equal to `pageType: 'api'`: +表示当前页为 api 页面。相当于`pageType: 'api'`： ```md --- @@ -54,7 +54,7 @@ api: true - Type: `Object` -The hero config of `home` page. It has following type: +`home` 页面的 hero 配置。它有以下类型： ```ts export interface Hero { @@ -73,7 +73,7 @@ export interface Hero { } ``` -For example, you can use the following front matter to specify the hero config of the page: +例如，你可以使用以下 Front Matter 来指定页面的 hero config： ```md --- @@ -101,7 +101,7 @@ hero: - Type: `Array` - Default: `[]` -The features config of `home` page. It has following type: +`home` 页面的功能配置。它有以下类型： ```ts export interface Feature { @@ -113,7 +113,7 @@ export interface Feature { export type Features = Feature[]; ``` -For example, you can use the following front matter to specify the features config of `home` page: +例如，你可以使用以下前端内容来指定 `home` 页面的 features 配置： ```md --- diff --git a/docs/zh/api/config-theme.md b/docs/zh/api/config-theme.md index ebac70b6..f80751ac 100644 --- a/docs/zh/api/config-theme.md +++ b/docs/zh/api/config-theme.md @@ -1,6 +1,6 @@ -# Theme Config +# 主题配置 -The theme config is under the `themeConfig` in root config. For example: +主题配置位于根配置中的 `themeConfig` 下。例如： ```js import { defineConfig } from 'islandjs'; @@ -17,14 +17,14 @@ export default defineConfig({ - Type: `string` - Default: `"Island"` -The title of the site.Different from `title` in root config, this title will be used in the navbar. For example: +站点的标题。与根配置中的 `title` 不同，此标题将用于导航栏中。比如： ```js import { defineConfig } from 'islandjs'; export default defineConfig({ themeConfig: { - siteTitle: 'my-site' + siteTitle: '我的主页' } }); ``` @@ -34,22 +34,22 @@ export default defineConfig({ - Type: `Array` - Default: `[]` -The navigation bar of the site. The `nav` config is an array of `NavItem`, which has following type: +网站的导航栏。 `nav` 配置是 `NavItem` 的数组，具有以下类型： ```ts interface NavItem { - // The text of the nav item + // 导航栏文本 text: string; - // The link href will be entered when click the nav item + // 导航栏链接 link: '/'; - // The active match rule of the nav item, optional + // 导航栏链接的激活规则 activeMatch: '^/$|^/'; } ``` -The `activeMatch` is used to match the current route, and the nav item will be highlighted when the route matches the `activeMatch` rule.By default, the `activeMatch` is the `link` of the nav item. +`activeMatch` 用于匹配当前路由，当路由匹配 `activeMatch` 规则时，nav 项会高亮显示。默认情况下，`activeMatch` 是 nav 项的 `link`。 -For example: +比如: ```js import { defineConfig } from 'islandjs'; @@ -71,29 +71,25 @@ export default defineConfig({ - Type: `Array` | `Object` -The sidebar of the site. +网站的侧边栏。 -`sidebar` config has two form: `array` and `object`. +`sidebar` 配置有两种形式：`array` 和 `object`。 -The `array` config is a list of `SidebarGroup`, which has following type: +`array` 配置是 `SidebarGroup` 的列表，具有以下类型： ```ts interface SidebarGroup { - // The text of the sidebar group text: string; - // The child items of the sidebar group items: SidebarItem[]; } type SidebarItem = { - // The text of item text: string; - // The link href of item link: string; }; ``` -For example: +比如: ```js import { defineConfig } from 'islandjs'; @@ -115,13 +111,13 @@ export default defineConfig({ }); ``` -The `object` config is a map for `SidebarGroup`, which has following type: +`object` 配置是 `SidebarGroup` 的映射类型，具有以下类型： ```ts Record; ``` -For example: +比如: ```js import { defineConfig } from 'islandjs'; @@ -150,20 +146,18 @@ export default defineConfig({ - Type: `Object` | `undefined` - Default: `undefined` -The edit link of the site.If it's undefined, the edit link feature will be disabled. +站点的编辑链接。如果未定义，编辑链接功能将被禁用。 -The `editLink` config is an object of `EditLink`, which has following type: +`editLink` 配置是 `EditLink` 的一个对象，它具有以下类型： ```ts export interface EditLink { - // Pattern for edit link. pattern: string; - // Custom text for edit link. text?: string; } ``` -For example: +比如： ```js import { defineConfig } from 'islandjs'; @@ -179,16 +173,14 @@ export default defineConfig({ }); ``` -`:path` will be replaced by the current page path. +`:path` 将被当前页面路径替换。 ## lastUpdatedText - Type: `string` - Default: `"Last Updated"` -The text of last updated time. - -For example: +上次更新时间的文本。比如： ```js import { defineConfig } from 'islandjs'; @@ -205,9 +197,9 @@ export default defineConfig({ - Type: `Object` - Default: `{}` -The footer of the home site. +主页的页脚。 -The `footer` config is an object of `Footer`, which has following type: +`footer` 配置是 `Footer` 的一个对象，它具有以下类型： ```ts export interface Footer { @@ -216,7 +208,7 @@ export interface Footer { } ``` -For example: +比如： ```js import { defineConfig } from 'islandjs'; @@ -236,9 +228,9 @@ export default defineConfig({ - Type: `Array` - Default: `[]` -The social links of the site. +网站的社交链接。 -The `socialLinks` config is an array of `SocialLink`, which has following type: +`socialLinks` 配置是 `SocialLink` 的数组，具有以下类型： ```ts export interface SocialLink { @@ -247,7 +239,7 @@ export interface SocialLink { } ``` -For example: +比如： ```js import { defineConfig } from 'islandjs'; @@ -264,16 +256,16 @@ export default defineConfig({ }); ``` -> In current version, the `icon` only supports `github`. +> 在当前版本中，`icon` 只支持 `github` ## outlineTitle - Type: `string` - Default: 'ON THIS PAGE' -Configure the title of the outline in the right sidebar. +在右侧边栏中配置大纲的标题。 -For example: +比如: ```js import { defineConfig } from 'islandjs'; diff --git a/docs/zh/guide/conventional-route.md b/docs/zh/guide/conventional-route.md index febd1f03..1c753a69 100644 --- a/docs/zh/guide/conventional-route.md +++ b/docs/zh/guide/conventional-route.md @@ -1,14 +1,14 @@ -# Conventional Route +# 约定式路由 -## What is Conventional Route +## 什么是约定式路由 -Island.js uses a file system routing, and the file path of the page will be simply mapped as a routing path, which will make the routing of the entire project very intuitive. +Island.js 使用的是文件系统路由，页面的文件路径会简单的映射为路由路径，这样会让整个项目的路由非常直观。 -For example, if you have a file named `foo.md` in the `docs` directory, then the routing path of this file will be `/foo`. +例如，如果在 `docs` 目录中有一个名为 `foo.md` 的文件，则该文件的路由路径将是 `/foo`。 -## Mapping Rules +## 映射规则 -Island.js will automatically scan the root directory and all subdirectories, and map the file path to the routing path. For example, if you have following file structure: +Island.js 会自动扫描根目录和所有子目录，并将文件路径映射到路由路径。例如，如果你有以下的文件结构： ```bash docs @@ -17,22 +17,22 @@ docs └── foo.md ``` -> In previous getting-started project, the start script is `island dev docs`, so the root directory is `docs`. +> 在之前的入门项目中，启动脚本是`island dev docs`，所以根目录是`docs`。 -Then the routing path of `bar.md` will be `/foo/bar`, and the routing path of `foo.md` will be `/foo`. +那么`bar.md`的路由路径会是`/foo/bar`，`foo.md`的路由路径会是`/foo`。 -The specific mapping rules are as follows: +具体映射规则如下： -| File path | Routing path | -| --------------- | ------------ | -| `index.md` | `/` | -| `/foo.md` | `/foo` | -| `/foo/bar.md` | `/foo/bar` | -| `/zoo/index.md` | `/zoo` | +| 文件路径 | 路由路径 | +| --------------- | ---------- | +| `index.md` | `/` | +| `/foo.md` | `/foo` | +| `/foo/bar.md` | `/foo/bar` | +| `/zoo/index.md` | `/zoo` | -## Custom Behavior +## 自定义行为 -If you want to customize the routing behavior, you can use the `route` field in the root config. For example: +如果要自定义路由行为，可以使用配置文件中的 `route` 字段。例如： ```ts import { defineConfig } from 'islandjs'; @@ -47,4 +47,4 @@ export default defineConfig({ }); ``` -You can see more details in [Config Extension](/en/api/config-extension). +更多细节可以参考 [配置扩展](/zh/api/config-extension)。 diff --git a/docs/zh/guide/custom-page.md b/docs/zh/guide/custom-page.md index 6c91add5..4031c00a 100644 --- a/docs/zh/guide/custom-page.md +++ b/docs/zh/guide/custom-page.md @@ -1,14 +1,14 @@ -# Custom Page +# 自定义页面 -## Motivation +## 为什么支持自定义页面？ -Sometimes you may want to add a custom page to your site. For example, you may want to add a page to introduce your team, or you may want to add a page to show your sponsors. +某些情况下你可能希望将自定义页面添加到你的站点。例如，你可能想要添加一个页面来介绍团队，或者可能想要添加一个页面来展示 Sponsors。 -So Island.js provides a way to add a custom page to your site. +因此除了用 md/mdx 文件来书写页面外， Island.js 也提供了一种向站点添加自定义页面的方法。 -## Usage +## 使用方法 -You can create a new file such as `custom.tsx` in the root dir, then you can add the following code: +你可以在根目录中创建一个新文件，例如 `custom.tsx`，然后可以添加以下代码： ```tsx export const pageType = 'custom'; @@ -18,7 +18,7 @@ export default function CustomPage() { } ``` -Then you can visit `/custom` route to see the custom page. So there are some tips for the custom page: +然后你可以访问 `/custom` 路由来查看自定义页面。其中有一些注意事项： -- 1. The custom page should be a React component, which should be the default export of the file. -- 2. The custom page should has a `pageType` export, which should be `custom`. +- 1. 自定义页面默认导出一个 React 组件。 +- 2. 自定义页面应该有一个 `pageType = 'custom'` 的导出。 diff --git a/docs/zh/guide/extension.md b/docs/zh/guide/extension.md index 7033fb0a..e2bab9fc 100644 --- a/docs/zh/guide/extension.md +++ b/docs/zh/guide/extension.md @@ -1,17 +1,17 @@ -# Extension +# 能力扩展 -Island.js is simple and it doesn't has own plugin system. But it is also flexible and extensible because it exposes a lot of ways to help you customize the behavior of the framework. +Island.js 使用很简单，虽然它没有自己的插件系统，但它也是灵活和可扩展的，因为它公开了很多接口来帮助你自定义框架的行为。 ## Vite -As the build tool of Island.js, Vite is also extensible. You can use the `vite` field in the root config to customize the behavior of Vite. For example: +作为 Island.js 的构建工具，Vite 也是可扩展的。你可以使用根配置中的 `vite` 字段来自定义 Vite 的行为。例如： ```ts import { defineConfig } from 'islandjs'; export default defineConfig({ vite: { - // Then your vite plugins will be merged with the default plugins + // 然后你自定义的 vite 插件将与默认插件合并 plugins: [ // ... ] @@ -19,26 +19,26 @@ export default defineConfig({ }); ``` -## Conventional Route +## 约定式路由 -The conventional route is implemented by a vite plugin. You can pass in the options to customize the plugin behavior. For example: +Island.js 通过 Vite 插件来约定式路由。你可以通过根配置中的 `route` 字段来自定义约定式路由的行为。例如： ```ts import { defineConfig } from 'islandjs'; export default defineConfig({ route: { - // These files will be excluded from the routing (support glob pattern) + // 这些文件将从路由中排除（支持 glob 模式） exclude: ['custom.tsx', 'component/**/*'] } }); ``` -You can see more details in [Config Extension](/en/api/config-extension#route). +你可以在 [扩展配置](/zh/api/config-extension#route) 中查看更多细节。 ## Markdown -You can customize the behavior of markdown compilation by using the `markdown` field in the root config. For example: +你可以使用根配置中的 `markdown` 字段自定义 Markdown 编译的行为。例如： ```ts import { defineConfig } from 'islandjs'; @@ -51,4 +51,4 @@ export default defineConfig({ }); ``` -See more details in [Config Extension](/en/api/config-extension#markdown). +你可以在[扩展配置](/zh/api/config-extension#markdown)中查看更多细节。 diff --git a/docs/zh/guide/spa-mode.md b/docs/zh/guide/spa-mode.md index f4659446..2c8fd525 100644 --- a/docs/zh/guide/spa-mode.md +++ b/docs/zh/guide/spa-mode.md @@ -1,16 +1,14 @@ -# SPA Mode +# SPA 模式 -## What is SPA Mode? +## 什么是 SPA 模式？ -By default, Island.js will generate a static site for every page and inject partial component javascript to make the site interactive. That's called `MPA` mode, in winch every page is a separate HTML file and when you click to another page, the browser will request a new HTML file. +默认情况下，Island.js 将为每个页面生成一个静态站点，并注入部分组件 JavaScript 以使站点具有交互性。这就是所谓的`MPA`模式，在 MPA 中，每个页面都是一个单独的 HTML 文件，当你点击跳转到另一个页面时，浏览器会请求一个新的 HTML 文件。 -On the other hand, you can use `SPA` mode to build a single page application. In SPA mode, Island.js will generate a single HTML file and inject all the javascript to make the site interactive. When you click to another page, the browser will not request a new HTML file, but only request a new javascript file to load the new page. +另一方面，你也可以使用 `SPA` 模式来构建单页应用程序。在 SPA 模式下，Island.js 将生成单个 HTML 文件并注入所有 JavaScript 以使站点具有交互性。当你点击另一个页面时，浏览器不会请求新的 HTML 文件，而只会请求新的 javascript 文件来加载新页面。 -As well as we analyzed before([MPA vs SPA](/en/guide/spa-vs-mpa)), SPA mode will have better performance and experience in subsequent pages, but with complete hydration and client script in the first page, the first page load performance will be worse than MPA mode. +## 如何使用？ -## How to use? - -You can use `enableSpa` option to enable SPA mode: +在 Island.js 中，你可以通过配置文件来开启 SPA 模式： ```js import { defineConfig } from 'islandjs'; @@ -20,4 +18,4 @@ export default defineConfig({ }); ``` -It's so easy to use SPA mode, but MPA mode is still the default mode because Island.js do the best optimize in MPA mode which is most different from other SSG frameworks. +使用 SPA 模式非常简单，但是 MPA 模式仍然是默认模式，也是我们推荐的模式，因为在 MPA 下 Island.js 采用 Islands 架构进行优化，拥有非常好的首屏性能。 diff --git a/docs/zh/guide/static-assets.mdx b/docs/zh/guide/static-assets.mdx index da2a641e..92dc2bb3 100644 --- a/docs/zh/guide/static-assets.mdx +++ b/docs/zh/guide/static-assets.mdx @@ -1,46 +1,44 @@ -# Assets handle +# 静态资源处理 -## Import Static assets +## 导入静态资源 -You can import static assets in your `markdown`(or `mdx`) file, and Island.js will handle it for you. - -Relative and absolute paths are both supported. For example, if you have an image in the same folder as your markdown file, you can reference it like this: +你可以在 `markdown`（或 `mdx`）文件中导入静态资源。相对路径和绝对路径都是支持的，例如，如果在 markdown 同级目录有一张图片，你可以像这样引用它： ```mdx ![](./island.png) ``` -Of course, in `mdx` file your can also use img tag directly: +当然，在 `mdx` 文件中你也可以直接使用 img 标签： ```mdx ``` -Island.js will response the image request based on your source file path and the relative path you provided. +Island.js 将会根据 mdx 路径和图片路径，自动找到图片并响应给浏览器。 -On the other hand, you can also use absolute path to import static assets.In this way, Island.js will look for the file in two places: +另一方面，也可以使用绝对路径导入静态资源。这样，Island.js 将会先后在两个地方查找文件： -- root dir served by Island.js, such as `docs` -- public folder in root dir +- 项目根目录，比如启动命令为 `island dev docs`，那么根目录就是 `docs` +- 项目根目录 `public` 文件夹 -For example, if root dir is `docs` and you have a file `docs/public/island.png`, you can reference it like this: +例如，如果根目录是 `docs` 并且你有一个文件 `docs/public/island.png`，你可以像这样引用它： ```mdx ![](/island.png) ``` -Then, if you have a file `docs/assets/island.png`, you can reference it like this: +同时，如果你有一个文件 `docs/assets/island.png`，你可以像这样引用它： ```mdx ![](/assets/island.png) ``` -## Public Files +## 公共资源 -As well as mentioned above, you can put your static assets in `public` folder, and Island.js will serve them for you.And in production build, -Island.js will copy all files in `public` folder to the output folder(`dist`). +上文提到过，你可以把你的静态资源放在 `public` 目录中，Island.js 将自动在 `public` 目录寻找资源。在生产环境中， +Island.js 会将 `public` 目录中的所有文件复制到产物目录（`dist`）。 -For example: +比如: ```bash docs @@ -48,7 +46,7 @@ docs │ └── island.png ``` -After build, you will get: +在生产环境构建后，Island.js 将会在 `dist` 目录下生成 `island.png` 文件： ```bash docs diff --git a/docs/zh/guide/use-mdx.mdx b/docs/zh/guide/use-mdx.mdx index 5689b101..a254ae0b 100644 --- a/docs/zh/guide/use-mdx.mdx +++ b/docs/zh/guide/use-mdx.mdx @@ -1,22 +1,22 @@ --- -title: 'Using MDX' +title: '使用 MDX' --- -# Using Mdx +# 使用 Mdx -Island.js supports [Mdx](https://mdxjs.com/), which is a powerful way to write content. You can write, import and use React components in Markdown file. +Island.js 支持 [Mdx](https://mdxjs.com/)，这是一种功能强大的内容开发方式，你可以在 Markdown 文件中导入和使用 React 组件。 ## Markdown -MDX is the super set of Markdown, which means you can write Markdown file as usual. For example: +MDX 是 Markdown 的超集，这意味着可以像往常一样编写 Markdown 文件。例如： ```md # Hello World ``` -## Use Components +## 使用组件 -When you want to use React components in Markdown file, you should name your file with `.mdx` extension. For example: +当你想在 Markdown 文件中使用 React 组件时，你应该使用 `.mdx` 扩展名来命名你的文件。例如： ```mdx // docs/index.mdx @@ -29,7 +29,7 @@ import { CustomComponent } from './custom'; ## Front Matter -You can use [Front Matter](https://jekyllrb.com/docs/front-matter/) to add metadata to your Markdown file. For example: +你可以在 Markdown 文件的开头添加 Front Matter，它是一个 YAML 格式的对象，用于定义一些元数据。例如： ```mdx --- @@ -37,9 +37,9 @@ title: Hello World --- ``` -> Note: by default, Island.js use h1 title as the title of html. +> 注意：默认情况下，Island.js 使用 h1 标题作为 html 的标题。 -You can also access the property defined in front matter, for example: +你还可以在正文中访问 Front Mattter 中定义的属性，例如： ```mdx --- @@ -49,10 +49,10 @@ title: Hello World # {meta.title} ``` -The properties defined in front matter will be passed to the component as `meta` property.So the final output will be: +前面定义的属性将作为 `meta` 属性传递给组件。所以最终输出将是： ```html

Hello World

``` -You can see more front matter config detail in [config-front-matter](/en/api/config-front-matter). +更多的配置详情请参考 [config-front-matter](/zh/api/config-front-matter)。