blackteay/fes.js
1
0
Fork 0
mirror of https://github.com/WeBankFinTech/fes.js.git synced 2025-04-05 19:41:57 +08:00
Code Issues Projects Releases Wiki Activity

docs: 复制中文文档到英文目录

Browse Source
This commit is contained in:
万纯 2021-03-05 19:10:39 +08:00
parent 1d182a9d3e
commit 54748f4306
65 changed files with 3028 additions and 3638 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

78
docs/.vuepress/configs/navbar/en.ts
View File

@ -6,78 +6,32 @@ export const en: NavbarConfig = [
link: '/guide/',
},
{
text: 'Reference',
children: [
text: 'Config',
link: '/reference/config/',
},
{
text: 'VuePress',
children: [
text: 'API',
link: '/reference/api/',
},
{
text: 'Plugin',
link: '/reference/plugin/',
},
{
text: 'CLI',
link: '/reference/cli.html',
},
'/reference/config.md',
'/reference/frontmatter.md',
'/reference/components.md',
'/reference/plugin-api.md',
'/reference/theme-api.md',
],
link: '/reference/cli/',
},
{
text: 'Bundlers',
children: [
'/reference/bundler/webpack.md',
'/reference/bundler/vite.md',
],
},
{
text: 'Default Theme',
children: [
'/reference/default-theme/config.md',
'/reference/default-theme/frontmatter.md',
'/reference/default-theme/components.md',
'/reference/default-theme/markdown.md',
],
},
{
text: 'Official Plugins',
link: '/reference/plugin/',
children: [],
},
],
},
{
text: 'Learn More',
text: 'More',
children: [
{
text: 'Advanced',
children: [
'/guide/advanced/markdown.md',
'/guide/advanced/theme.md',
'/guide/advanced/plugin.md',
],
},
{
text: 'Resources',
children: [
'/contributing.md',
{
text: 'Changelog',
text: '更新日志',
link:
'https://github.com/vuepress/vuepress-next/blob/main/CHANGELOG.md',
'https://github.com/WeBankFinTech/fes.js/blob/master/CHANGELOG.md',
},
{
text: 'Awesome VuePress',
link: 'https://github.com/vuepress/awesome-vuepress',
},
{
text: 'v1 docs',
link: 'https://v1.vuepress.vuejs.org',
},
{
text: 'v0 docs',
link: 'https://v0.vuepress.vuejs.org',
},
],
text: 'v1 文档',
link: 'https://webank.gitee.io/fes.js-v0/',
},
],
},

109
docs/.vuepress/configs/sidebar/en.ts
View File

@ -4,84 +4,71 @@ export const en: SidebarConfig = {
'/guide/': [
{
isGroup: true,
text: 'Guide',
text: '介绍',
children: [
'/guide/README.md',
'/guide/getting-started.md',
'/guide/configuration.md',
'/guide/page.md',
'/guide/markdown.md',
'/guide/assets.md',
'/guide/i18n.md',
'/guide/deployment.md',
'/guide/theme.md',
],
},
{
isGroup: true,
text: '基础',
children: [
'/guide/directory-structure.md',
'/guide/config.md',
'/guide/route.md',
'/guide/plugin.md',
'/guide/bundler.md',
],
'/guide/template.md',
'/guide/mock.md',
'/guide/env.md',
]
},
],
'/guide/advanced/': [
{
isGroup: true,
text: 'Advanced',
text: '进阶',
children: [
'/guide/advanced/markdown.md',
'/guide/advanced/theme.md',
'/guide/advanced/plugin.md',
],
]
},
"/guide/contributing.md",
"/guide/faq.md"
],
'/reference/': [
{
isGroup: true,
text: 'VuePress Reference',
children: [
'/reference/cli.md',
'/reference/config.md',
'/reference/frontmatter.md',
'/reference/components.md',
'/reference/plugin-api.md',
'/reference/theme-api.md',
'/reference/config/': [
'/reference/config/README.md'
],
},
],
'/reference/bundler/': [
{
isGroup: true,
text: 'Bundlers Reference',
children: ['/reference/bundler/webpack.md', '/reference/bundler/vite.md'],
},
],
'/reference/default-theme/': [
{
isGroup: true,
text: 'Default Theme Reference',
children: [
'/reference/default-theme/config.md',
'/reference/default-theme/frontmatter.md',
'/reference/default-theme/components.md',
'/reference/default-theme/markdown.md',
],
},
'/reference/api/': [
'/reference/api/README.md'
],
'/reference/plugin/': [
{
isGroup: true,
text: 'Official Plugins Reference',
text: 'Presets',
children: [
'/reference/plugin/active-header-links.md',
'/reference/plugin/back-to-top.md',
'/reference/plugin/container.md',
'/reference/plugin/debug.md',
'/reference/plugin/docsearch.md',
'/reference/plugin/git.md',
'/reference/plugin/google-analytics.md',
'/reference/plugin/medium-zoom.md',
'/reference/plugin/nprogress.md',
'/reference/plugin/palette-stylus.md',
'/reference/plugin/pwa.md',
'/reference/plugin/pwa-popup.md',
],
},
{
isGroup: true,
text: 'Plugins',
children: [
'/reference/plugin/plugins/access.md',
'/reference/plugin/plugins/enums.md',
'/reference/plugin/plugins/icon.md',
'/reference/plugin/plugins/jest.md',
'/reference/plugin/plugins/layout.md',
'/reference/plugin/plugins/locale.md',
'/reference/plugin/plugins/model.md',
'/reference/plugin/plugins/request.md',
'/reference/plugin/plugins/vuex.md',
],
},
{
isGroup: true,
text: '插件开发',
children: [
'/reference/plugin/api.md'
],
},
],
'/reference/cli/': [
'/reference/cli/README.md',
],
}

69
docs/README.md
View File

@ -1,41 +1,42 @@
---
home: true
title: Home
heroImage: /hero.png
title: 首页
heroImage: /logo.png
actions:
- text: Get Started
link: /guide/getting-started.html
- text: 快速上手
link: /zh/guide/getting-started.html
type: primary
- text: Introduction
link: /guide/
- text: 项目简介
link: /zh/guide/
type: secondary
features:
- title: Simplicity First
details: Minimal setup with markdown-centered project structure helps you focus on writing.
- title: Vue-Powered
details: Enjoy the dev experience of Vue, use Vue components in markdown, and develop custom themes with Vue.
- title: Performant
details: VuePress generates pre-rendered static HTML for each page, and runs as an SPA once a page is loaded.
footer: MIT Licensed | Copyright © 2018-present Evan You
- title: Fast
details: Fes内置了路由、开发、构建等，并且提供测试、布局、权限、国际化、状态管理、API请求、数据字典、SvgIcon等插件，可以满足大部分日常开发需求。
- title: Easy
details: 基于Vue.js 3.0，上手简单。贯彻“约定优于配置”思想，设计插件上尽可能用约定替代配置，同时提供统一的插件配置入口，简单简洁又不失灵活。提供一致性的API入口，一致化的体验，学习起来更轻松。
- title: Strong
details: 只需要关心页面内容，减少犯错的机会！提供单元测试、覆盖测试的能力保障项目质量。
- title: 可扩展
details: 借鉴Umi实现了完整的生命周期和插件化机制，插件可以管理项目的编译时和运行时，能力均可以通过插件封装进来，在 Fes.js 中协调有序的运行。
- title: 面向未来
details: 在满足需求的同时，我们也不会停止对新技术的探索。已使用Vue3.0来提升应用性能，已使用webpack5提升构建性能和实现微服务，未来会探索vite等新技术。
footer: MIT Licensed | Copyright © 2020-present Webank
---
### As Easy as 1, 2, 3
## 像数 1, 2, 3 一样容易
<CodeGroup>
<CodeGroupItem title="YARN" active>
```bash
# install in your project
yarn add -D vuepress@next
# 创建模板
yarn create @fesjs/fes-app myapp
# create a markdown file
echo '# Hello VuePress' > README.md
# 安装依赖
yarn
# start writing
yarn vuepress dev
# build to static files
yarn vuepress build
# 运行
yarn dev
```
</CodeGroupItem>
@ -43,18 +44,22 @@ yarn vuepress build
<CodeGroupItem title="NPM">
```bash
# install in your project
npm install -D vuepress@next
# 创建模板
npx @fesjs/create-fes-app myapp
# create a markdown file
echo '# Hello VuePress' > README.md
# 安装依赖
npm install
# start writing
npx vuepress dev
# build to static files
npx vuepress build
# 运行
npm run dev
```
</CodeGroupItem>
</CodeGroup>
## 反馈
| Github Issue | 微信群 | Fes.js开源运营小助手 |
| --- | --- | --- |
| [@fesjs/fes.js/issues](https://github.com/WeBankFinTech/fes.js/issues) | <img src="https://i.loli.net/2020/09/11/2XhKtPZd6NFVbDE.png" width="250" /> | <img src="https://i.loli.net/2020/09/16/sxwr62CKhmYOUyV.jpg" height="250"/> |

108
docs/contributing.md
View File

@ -1,108 +0,0 @@
---
sidebar: auto
---
# Contributing Guide
## Overview
This repository employs a [monorepo](https://en.wikipedia.org/wiki/Monorepo) setup with [yarn classic workspaces](https://classic.yarnpkg.com/en/docs/workspaces), and hosts a number of associated but separated packages in the `packages` directory:
- `@vuepress/core`: The VuePress core. Provides pure Node API to generate VuePress app, including page handling, plugin system and data preparation.
- `@vuepress/client`: The VuePress client package. Provides the client entry, and exports types and composable utils that can be used in client side development.
- `@vuepress/bundler-webpack`: The VuePress bundler package with webpack. Use webpack to `dev` and `build` VuePress app that generated by `@vuepress/core`.
- `@vuepress/cli`: The VuePress command line interface (CLI) package. It will resolve user config file, and create VuePress app with `@vuepress/core`, then use `@vuepress/bundler-${name}` to execute corresponding command.
- `@vuepress/theme-default`: The VuePress default theme.
- `@vuepress/plugin-${name}`: Official plugins.
- `@vuepress/shared`: Utilities that shared between node side and client side.
- `@vuepress/utils`: Utilities that should only be used in node side.
- `vuepress`: Simply a wrapper of `@vuepress/cli`, which requires `@vuepress/bundler-webpack` and `@vuepress/theme-default` as dependencies. If users want to use default theme with webpack, they can simply install this package.
## Development Setup
Pre-requirement:
- [Node.js](http://nodejs.org) **version 12+**
- [Yarn v1 classic](https://classic.yarnpkg.com/en/docs/install)
Clone the repo, and install dependencies:
```bash
yarn
```
Start watching source files:
```bash
yarn dev
```
Open another terminal, and start developing the documentation site:
```bash
yarn docs:dev
```
Main tools that used in this project:
- [TypeScript](https://www.typescriptlang.org/) as the development language
- [Jest](https://jestjs.io/) for unit testing
- [ESLint](https://eslint.org/) + [Prettier](https://prettier.io/) for code linting and formatting
## Scripts
### `yarn build`
The `build` script uses `tsc` to compile typescript source files to javascript dist files.
You may need to run this script first after your clone this repository, because the dist files are ignored by `.gitignore`.
### `yarn copy`
The `copy` script of root project runs `copy` script in all packages, copying some resources from source directory to dist directory.
Some source files (e.g. `.vue`, `.styl` files) can not be processed by `build` script, but should keep the same relative path in the dist directory.
You may need to run this script after your clone this repository, too.
### `yarn dev`
The `dev` script runs `copy` and `build` scripts in watch mode.
### `yarn clean`
The `clean` script runs `clean` script in all packages, cleaning all the dist files and caches. In other words, it will remove all the files that generated by `build`, `copy` and `dev` scripts.
It's used before you want to re-build source files from a clean / initial state.
### `yarn docs:*`
#### `yarn docs:build`, `yarn docs:dev`, `yarn docs:clean`
The `docs:` prefix indicates that these scripts are for documentation, i.e. the `docs` directory.
VuePress is using itself to build its own documentation site.
You need to run `yarn build && yarn copy` to build VuePress source files first, then run these `docs:` scripts to develop and build our documentation.
#### `yarn docs:serve`
Serve the documentation site locally.
You need to run `yarn docs:build` first to generate the documentation dist files, and then run `yarn docs:serve` to serve them.
### `yarn lint`
The `lint` script uses ESLint to check all source files.
### `yarn test`
The `test` script uses Jest to run unit testings.

76
docs/guide/README.md
View File

@ -1,39 +1,75 @@
# Introduction
VuePress is a markdown-centered static site generator. You can write your content (documentations, blogs, etc.) in [Markdown](https://en.wikipedia.org/wiki/Markdown), then VuePress will help you to generate a static site to host them.
# 介绍
The purpose of creating VuePress was to support the documentation of Vue.js and its sub-projects, but now it has been helping a large amount of users to build their documentation, blogs, and other static sites.
## How It Works
A VuePress site is in fact a single-page application (SPA) powered by [Vue](https://v3.vuejs.org/) and [Vue Router](https://next.router.vuejs.org).
## 痛点
Routes are generated according to the relative path of your markdown files. Each Markdown file is compiled into HTML with [markdown-it](https://github.com/markdown-it/markdown-it) and then processed as the template of a Vue component. This allows you to directly use Vue inside your Markdown files and is great when you need to embed dynamic content.
在开发一个前端项目之前，我们可能需要做如下准备工作：
- 搭建开发环境
- 约定代码规范
- 封装API请求
- 配置路由
- 实现布局、菜单、导航
- 实现登录
- 权限管理
- ...
During development, we start a normal dev-server, and serve the VuePress site as a normal SPA. If you’ve used Vue before, you will notice the familiar development experience when you are writing and developing with VuePress.
除了准备工作之外，还会遇到很多相似的业务类型，比如中后台应用大多都是工作台、增删改查、权限、图表等。如果每次项目都完全手动处理一遍，不仅耗费时间，久而久之可能会存在多种技术栈、开发规范，导致开发流程不统一，历史项目越来越难维护。所以我们需要一套完整的解决方案，管理开发到部署整个流程。
During build, we create a server-rendered version of the VuePress site and render the corresponding HTML by virtually visiting each route. This approach is inspired by [Nuxt](https://nuxtjs.org/)'s `nuxt generate` command and other projects like [Gatsby](https://www.gatsbyjs.org/).
## Fes.js 是什么？
## Why Not ...?
Fes.js 是一个好用的前端应用解决方案。Fes.js 以 Vue 3.0 和路由为基础，同时支持配置式路由和约定式路由，并以此进行功能扩展。配以覆盖编译时和运行时生命周期完善的插件体系，支持各种功能扩展和业务需求。
### Nuxt
它主要具备以下功能：
- :rocket: __快速__ ，内置了路由、开发、构建等，并且提供测试、布局、权限、国际化、状态管理、API请求、数据字典、SvgIcon等插件，可以满足大部分日常开发需求。
Nuxt is an outstanding Vue SSR framework, and it is capable of doing what VuePress does. But Nuxt is designed for building applications, while VuePress is more lightweight and focused on content-centric static sites.
- :firecracker: __简单__ ，基于Vue.js 3.0，上手简单。贯彻“约定优于配置”思想，设计插件上尽可能用约定替代配置，同时提供统一的插件配置入口，简单简洁又不失灵活。提供一致性的API入口，一致化的体验，学习起来更轻松。
### VitePress
- 💪 __健壮__ ，只需要关心页面内容，减少写BUG的机会！提供单元测试、覆盖测试能力保障项目质量。
VitePress is the little brother of VuePress. It's also created and maintained by our Vue.js team. It's even more lightweight and faster than VuePress. However, as a tradeoff, it's more opinionated and less configurable. For example, it does not support plugins. But VitePress is powerful enough to make your content online if you don't need advanced customizations.
- :package: __可扩展__ ，借鉴Umi实现了完整的生命周期和插件化机制，插件可以管理项目的编译时和运行时，能力均可以通过插件封装进来，在 Fes.js 中协调有序的运行。
It might not be an appropriate comparison, but you can take VuePress and VitePress as Laravel and Lumen.
- 📡 __面向未来__ ，在满足需求的同时，我们也不会停止对新技术的探索。已使用Vue3.0来提升应用性能，已使用webpack5提升构建性能和实现微服务，未来会探索vite等新技术。
### Docsify / Docute
Both are great projects and also Vue-powered. Except they are both fully runtime-driven and therefore not SEO-friendly. If you don’t care for SEO and don’t want to mess with installing dependencies, these are still great choices.
## Fes.js 如何工作？
### Hexo
### 架构
![架构](/framework.png "架构")
Hexo has been serving the Vue 2.x docs well. The biggest problem is that its theming system is static and string-based - we want to take advantage of Vue for both the layout and the interactivity. Also, Hexo’s Markdown rendering isn’t the most flexible to configure.
Fes.js 把大家常用的技术栈封装成一个个插件进行整理，收敛到一起，让大家只用 Fes.js 就可以完成 80% 的日常工作。
### GitBook
### 插件和插件集
<p>
<img src="/plugins.png" alt="插件" title="插件" style="width: 500px" class="medium-zoom-image">
</p>
Fes.js 支持插件和插件集，通过这张图应该很好理解到他们的关系，通过插件集我们把插件收敛依赖然后支持不同的业务类型。
We’ve been using GitBook for most of our sub project docs. The primary problem with GitBook is that its development reload performance is intolerable with a large amount of files. The default theme also has a pretty limiting navigation structure, and the theming system is, again, not Vue based. The team behind GitBook is also more focused on turning it into a commercial product rather than an open-source tool.
### .fes 临时文件
.fes 临时目录是整个 Fes.js 项目的发动机，你的入口文件、路由等等都在这里，这些是由 fes 内部插件及三方插件生成的。
你通常会在 .fes 下看到以下目录
```
+ .fes
+ core # 内部插件生成
+ pluginA # 外部插件生成
+ presetB # 外部插件生成
+ fes.js # 入口文件
```
临时文件是 Fes.js 中非常重要的一部分，框架或插件会根据你的代码生成临时文件，这些原来需要放在项目里的脏乱差的部分都被藏在了这里。
你可以在这里调试代码，但不要在 .git 仓库里提交他，因为他的临时性，每次启动 fes 时都会被删除并重新生成。
## 为什么不是 ...?
### Vue CLI
Vue CLI 是基于 Vue.js 进行快速开发的完整系统，提供交互式脚手架、丰富的官方插件，并且可通过插件进行扩展，他在打包层把体验做到了极致，但是不包含路由，不是框架。所以，如果大家想基于他修改部分配置，或者希望在打包层之外也做技术收敛时，就会遇到困难。
### UMI
UMI 是个很好的选择，Fes.js 很多功能是借鉴 UMI 做的。UMI 是基于 React 封装的应用级框架，贯彻着函数式编程的思维。而 Vue 有所不同，虽然 Vue 3.0 向函数式迈了一大步，但大家可能依然喜欢编写 `.vue`文件，而非 `.jsx` 文件。两种思维方式会导致部分API设计上有所差异，虽然 UMI 有 `plugin-vue` ，但不太 "vue"。推荐喜欢 React 的同学使用 UMI。

102
docs/guide/advanced/markdown.md
View File

@ -1,102 +0,0 @@
# Markdown and Vue SFC
Each Markdown file is first compiled into HTML, and then converted to a Vue SFC. In other words, you can take Markdown as Vue SFC:
- Blocks `<script>` and `<style>` are treated as Vue SFC blocks as they are. In other words, they are hoisted from the `<template>` block to the top-level of SFC.
- Everything outside `<script>` and `<style>` will be compiled into HTML, and be treated as Vue SFC `<template>` block.
Here comes an example:
**Input**
```vue
_Hello, {{ msg }}_
<RedDiv>
_Current count is: {{ count }}_
</RedDiv>
<button @click="count++">Click Me!</button>
<script>
import { h, ref } from 'vue'
const RedDiv = (_, ctx) => h(
'div',
{
class: 'red-div',
},
ctx.slots.default()
)
export default {
components: {
RedDiv,
},
setup() {
const msg = 'Vue in Markdown'
const count = ref(0)
return {
msg,
count,
}
}
}
</script>
<style>
.red-div {
color: red;
}
</style>
```
**Output**
_Hello, {{ msg }}_
<RedDiv>
_Current count is: {{ count }}_
</RedDiv>
<button @click="count++">Click Me!</button>
<script>
import { h, ref } from 'vue'
const RedDiv = (_, ctx) => h(
'div',
{
class: 'red-div',
},
ctx.slots.default()
)
export default {
components: {
RedDiv,
},
setup() {
const msg = 'Vue in Markdown'
const count = ref(0)
return {
msg,
count,
}
}
}
</script>
<style>
.red-div {
color: red;
}
</style>

3
docs/guide/advanced/plugin.md
View File

@ -1,3 +0,0 @@
# Writing a Plugin
> TODO

3
docs/guide/advanced/theme.md
View File

@ -1,3 +0,0 @@
# Writing a Theme
> TODO

104
docs/guide/assets.md
View File

@ -1,104 +0,0 @@
# Assets
## Relative URLs
You can reference any assets using relative URLs in your Markdown content:
```md
![An image](./image.png)
```
This is generally the suggested way to import images, as users usually place images near the Markdown file that references them.
## Public Files
You can put some static assets inside public directory, and they will be copied to the root of the generated directory.
The default public directory is `.vuepress/public`, which can be changed in config.
It would be useful in some cases:
- You may need to provide static assets that are not directly referenced in any of your Markdown files, for example, favicon and PWA icons.
- You may need to serve some shared static assets, which may even be referenced outside your site, for example, logo images.
- You may want to reference images using absolute URLs in your Markdown content.
Take our documentation source files as an example, we are putting the logo of VuePress inside the public directory:
```bash
└─ docs
├─ .vuepress
| └─ public
| └─ hero.png # <- Logo file
└─ guide
└─ assets.md # <- Here we are
```
We can reference our logo in current page like this:
**Input**
```md
![VuePress Logo](/hero.png)
```
**Output**
![VuePress Logo](/hero.png)
::: tip
Config reference: [public](../reference/config.md#public)
:::
### Base Helper
If your site is deployed to a non-root URL, i.e. the [base](../reference/config.md#base) is not `"/"`, you will need to prepend the `base` to the absolute URLs of your public files.
For example, if you plan to deploy your site to `https://foo.github.io/bar/`, then `base` should be set to `"/bar/"`, and you have to reference your public files in Markdown like this:
```md
![VuePress Logo](/bar/hero.png)
```
Obviously, it is brittle if you ever decide to change the `base`. This is the reason why we suggest to reference static assets using relative URLs.
To help with that, VuePress provides a built-in helper `$withBase` that generates the correct path:
```md
<img :src="$withBase('/hero.png')" alt="VuePress Logo">
```
The helper is verbose in Markdown. So it might be more helpful for theme and plugin authors.
::: tip
Config reference: [base](../reference/config.md#base)
:::
## Packages and Path Aliases
Although it is not a common usage, you can reference images from dependent packages:
```bash
npm install -D package-name
```
```md
![Image from dependency](package-name/image.png)
```
The path aliases that set in config file are also supported:
```js
module.exports = {
alias: {
'@alias': '/path/to/some/dir',
},
}
```
```md
![Image from path alias](@alias/image.png)
```
::: tip
Config reference: [alias](../reference/config.md#alias)
:::

3
docs/guide/bundler.md
View File

@ -1,3 +0,0 @@
# Bundler
> TODO

79
docs/guide/config.md Normal file
View File

@ -0,0 +1,79 @@
# 配置
Fes.js 约定 `.fes.js` 文件为项目基础配置文件，一份常见的配置示例如下：
```js
export default {
base: '/foo/',
publicPath: '/',
devServer: {
port: 8080
}
mock: {
prefix: '/v2'
},
proxy: {
'/v2': {
'target': 'https://api.douban.com/',
'changeOrigin': true,
},
},
layout: {
title: "Fes.js",
footer: 'Created by MumbelFe',
multiTabs: false,
menus: [{
name: 'index'
}, {
name: 'onepiece'
}, {
name: 'store'
}, {
name: 'simpleList'
}]
}
}
```
## 配置文件
可以新建 `.fes.local.js` 作为本地临时配置文件。这份配置会和 `.fes.js` 做 deep merge 后形成最终配置。
```js
// .fes.js
export default { mock: false };
// .fes.local.js
export default {
mock: true,
dvServer: { port: 8080 }
};
```
最终的配置是：
```js
{
mock: true,
devServer: { port: 8080 }
};
```
::: tip
`.fes.local.js` 仅在 fes dev 时有效。
`.fes.local.js` 是本地验证使用的临时配置，请将其添加到 `.gitignore`，务必不要提交到 git 仓库中。
`.fes.local.js` 配置的优先级最高，比 `FES_ENV` 指定的配置更高。
:::
## 多环境多份配置
可以通过环境变量 `FES_ENV` 区分不同环境，来指定配置文件。
```js
// .fes.js
export default { mock: false };
// .fes.local.js
export default {
mock: true,
dvServer: { port: 8080 }
};
```
根据指定的 `FES_ENV` 拿对应的配置，这份配置会和 `.fes.js` 做 deep merge 后形成最终配。
::: tip
`FES_ENV` 指定的配置优先级高于 `.fes.js` 文件的配置
:::

84
docs/guide/configuration.md
View File

@ -1,84 +0,0 @@
# Configuration
## Config File
Without any configuration, the VuePress site is pretty minimal. To customize your site, let’s first create a `.vuepress` directory inside your docs directory. This is where all VuePress-specific files will be placed. Your project structure is probably like this:
```
├─ docs
│ ├─ .vuepress
│ │ └─ config.js
│ └─ README.md
├─ .gitignore
└─ package.json
```
The essential file for configuring a VuePress site is `.vuepress/config.js`, which should export a JavaScript object. If you are using TypeScript, you can use `.vuepress/config.ts` instead to get better types hint for VuePress Config.
<CodeGroup>
<CodeGroupItem title="JS" active>
```js
module.exports = {
lang: 'en-US',
title: 'Hello, VuePress!',
description: 'This is my first VuePress site',
themeConfig: {
logo: 'https://vuejs.org/images/logo.png',
},
}
```
</CodeGroupItem>
<CodeGroupItem title="TS">
```ts
import type { UserConfig, DefaultThemeOptions } from 'vuepress'
const config: UserConfig<DefaultThemeOptions> = {
lang: 'en-US',
title: 'Hello VuePress',
description: 'Just playing around',
themeConfig: {
logo: 'https://vuejs.org/images/logo.png',
},
}
export = config
```
</CodeGroupItem>
</CodeGroup>
::: tip
We will refer the config object as **VuePress Config**.
:::
## Config Scopes
You may have noticed that there is a `themeConfig` option in VuePress Config.
Options outside `themeConfig` are **Site Config**, while options inside `themeConfig` are **Theme Config**.
### Site Config
Site config means that, no matter what theme you are using, these configurations are always valid.
As we know, every site should have its own `lang`, `title`, `description`, etc. Thus, VuePress has built-in support for those options.
::: tip
Check out the [Config Reference](../reference/config.md) for a full list of site config.
:::
### Theme Config
Theme config will be processed by VuePress theme, so it depends on the theme you are using.
If you don't specify the `theme` option of VuePress Config, the default theme will be used.
::: tip
Check out the [Default Theme > Config Reference](../reference/default-theme/config.md) for theme config of default theme.
:::

70
docs/guide/contributing.md Normal file
View File

@ -0,0 +1,70 @@
# 贡献指南
## 概览
项目仓库借助于 [Yarn Classic 工作区](https://classic.yarnpkg.com/zh-Hans/docs/workspaces) 来实现 [Monorepo](https://en.wikipedia.org/wiki/Monorepo) ，在 `packages` 目录下存放了多个互相关联的独立 Package 。
- `@fesjs/create-fes-app`: 创建项目模板模块。提供`create-fes-app`命令，提供创建多种类型项目模板的能力。
- `@fesjs/fes`: 入口模块。提供`fes`命令和 API 入口。
- `@fesjs/compiler`: 编译时插件管理模块。定义插件的生命周期、插件配置、插件通讯机制等。
- `@fesjs/runtime`: 运行时插件模块。集成了vue-router，定义运行时插件生命周期、插件通讯机制。
- `@fesjs/preset-build-in`: 内置插件集。包含`dev`、`build`等命令，集成webpack5+babel，提供方便编写插件的API，入口文件处理，路由处理等能力。
- `@fesjs/fes-template`: 适用于PC类型的模板项目。
- `@fesjs/fes-template-h5`: 适用于H5类型的模板项目。
- `@fesjs/plugin-${name}`: 官方插件。
- `@fesjs/fes`: 是 `@fesjs/compiler` + `@fesjs/runtime` + `@fesjs/preset-build-in` 的封装。用户只需要安装此依赖和额外的插件或者插件集。
## 开发配置
开发要求：
- [Node.js](http://nodejs.org) **version 12+**
- [Yarn v1 classic](https://classic.yarnpkg.com/zh-Hans/docs/install)
克隆代码仓库，并安装依赖：
```bash
yarn
```
监听源文件修改：
```bash
yarn build
```
打开另一个终端，开始开发项目文档网站：
```bash
yarn docs:dev
```
本项目开发使用的一些主要工具：
- [Jest](https://jestjs.io/) 用于单元测试
- [ESLint](https://eslint.org/) + [Prettier](https://prettier.io/) 用于代码检查和格式化
- [@umi/father](https://github.com/umijs/father) 用于将ES6语法编译成ES5或者CommonJS
## 开发脚本
### `yarn build`
`build` 命令会使用 `father-build` 将 ES6 编译为 CommonJS。
本项目在编写Node端的代码时也用ES6，所以你在克隆代码仓库后，可能需要先执行该命令来确保项目代码可以顺利运行，因为编译后的 JS 文件被 `.gitignore` 排除在仓库以外了。
### `yarn docs:dev`
`docs:` 前缀表明，这些命令是针对文档 (documentation) 进行操作的，即 `docs` 目录。
使用 Vue Press在本地启动文档网站服务器，用于实时查看文档效果。
### 调试功能
在开发完插件代码后，需要在template项目中验证功能
- 进入`packages/template`目录
- 执行`yarn dev`

205
docs/guide/deployment.md
View File

@ -1,205 +0,0 @@
# Deployment
The following guides are based on some shared assumptions:
- You are placing your Markdown source files inside the `docs` directory of your project;
- You are using the default build output location (`.vuepress/dist`);
- You are using [yarn classic](https://classic.yarnpkg.com/en/) as package manager, while npm is also supported;
- VuePress is installed as a local dependency in your project, and you have setup the following script in `package.json`:
```json
{
"scripts": {
"docs:build": "vuepress build docs"
}
}
```
## GitHub Pages
1. Set the correct [base](../reference/config.md#base) config.
If you are deploying to `https://<USERNAME>.github.io/`, you can omit this step as `base` defaults to `"/"`.
If you are deploying to `https://<USERNAME>.github.io/<REPO>/`, for example your repository is at `https://github.com/<USERNAME>/<REPO>`, then set `base` to `"/<REPO>/"`.
2. Choose your preferred CI tools. Here we take [GitHub Actions](https://github.com/features/actions) as an example.
Create `.github/workflows/docs.yml` to set up the workflow.
::: details Click to expand sample config
```yaml
name: docs
on:
# trigger deployment on every push to main branch
push:
branches: [main]
# trigger deployment manually
workflow_dispatch:
jobs:
docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
with:
# fetch all commits to get last updated time or other git log info
fetch-depth: 0
- name: Setup Node.js
uses: actions/setup-node@v1
with:
# choose node.js version to use
node-version: '14'
# cache node_modules
- name: Cache dependencies
uses: actions/cache@v2
id: yarn-cache
with:
path: |
**/node_modules
key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
restore-keys: |
${{ runner.os }}-yarn-
# install dependencies if the cache did not hit
- name: Install dependencies
if: steps.yarn-cache.outputs.cache-hit != 'true'
run: yarn --frozen-lockfile
# run build script
- name: Build VuePress site
run: yarn docs:build
# please check out the docs of the workflow for more details
# @see https://github.com/crazy-max/ghaction-github-pages
- name: Deploy to GitHub Pages
uses: crazy-max/ghaction-github-pages@v2
with:
# deploy to gh-pages branch
target_branch: gh-pages
# deploy the default output dir of VuePress
build_dir: docs/.vuepress/dist
```
:::
::: tip
Please refer to [GitHub Pages official guide](https://pages.github.com/) for more details.
:::
## GitLab Pages
1. Set the correct [base](../reference/config.md#base) config.
If you are deploying to `https://<USERNAME>.gitlab.io/`, you can omit `base` as it defaults to `"/"`.
If you are deploying to `https://<USERNAME>.gitlab.io/<REPO>/`, for example your repository is at `https://gitlab.com/<USERNAME>/<REPO>`, then set `base` to `"/<REPO>/"`.
2. Create `.gitlab-ci.yml` to set up [GitLab CI](https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/) workflow.
::: details Click to expand sample config
```yaml
# choose a docker image to use
image: node:14-buster
pages:
# trigger deployment on every push to main branch
only:
- main
# cache node_modules
cache:
paths:
- node_modules/
# install dependencies and run build script
script:
- yarn --frozen-lockfile
- yarn docs:build --dest public
artifacts:
paths:
- public
```
:::
::: tip
Please refer to [GitLab Pages official guide](https://docs.gitlab.com/ce/user/project/pages/#getting-started) for more details.
:::
## Google Firebase
1. Make sure you have [firebase-tools](https://www.npmjs.com/package/firebase-tools) installed.
2. Create `firebase.json` and `.firebaserc` at the root of your project with the following content:
`firebase.json`:
```json
{
"hosting": {
"public": "./docs/.vuepress/dist",
"ignore": []
}
}
```
`.firebaserc`:
```json
{
"projects": {
"default": "<YOUR_FIREBASE_ID>"
}
}
```
3. After running `yarn docs:build`, deploy using the command `firebase deploy`.
::: tip
Please refer to [Firebase CLI official guide](https://firebase.google.com/docs/cli) for more details.
:::
## Heroku
1. Install [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli).
2. Create a Heroku account by [signing up](https://signup.heroku.com).
3. Run `heroku login` and fill in your Heroku credentials:
```bash
heroku login
```
4. Create a file called `static.json` in the root of your project with the below content:
`static.json`:
```json
{
"root": "./docs/.vuepress/dist"
}
```
This is the configuration of your site; read more at [heroku-buildpack-static](https://github.com/heroku/heroku-buildpack-static).
## Netlify
1. On [Netlify](https://netlify.com), set up a new project from GitHub with the following settings:
- **Build Command:** `yarn docs:build`
- **Publish directory:** `docs/.vuepress/dist`
2. Set [Environment variables](https://docs.netlify.com/configure-builds/environment-variables) to choose node version:
- `NODE_VERSION`: 14
3. Hit the deploy button.
## Vercel
See [Creating and Deploying a VuePress App with Vercel](https://vercel.com/guides/deploying-vuepress-to-vercel).

67
docs/guide/directory-structure.md Normal file
View File

@ -0,0 +1,67 @@
# 目录结构
在[快速上手](./getting-started.html)中，大家对框架应该有初步的印象，接下来我们了解下目录结构。Fes.js 遵循 `约定优于配置` 的原则，一个基础的 Fes.js 项目大致是这样的：
```
fes-template
├── package.json
├── tsconfig.json
├── mock.js
├── .fes.js
├── .env
├── dist
├── public
│ └── index.html
└── src
├── .fes
└── pages
│ └── index.vue
└── app.js
```
### 根目录
#### package.json
包含插件和插件集，以 `@fesjs/preset-`、`@fesjs/plugin-`、`fes-preset-` 和 `fes-plugin-` 开头的依赖会被自动注册为插件或插件集。
#### tsconfig.json
解决 `@fesjs/fes` 和使用 `@` 的 API 提示
#### .fes.js
配置文件，包含 Fes.js 内置功能和插件的配置。
#### .env
定义环境变量。
比如 `.env` 文件内容如下：
```
PORT=8888
FES_ENV=prod
```
等同于 node 端运行时，设置如下：
```
process.env.PORT = '8888';
process.env.FES_ENV = 'prod';
```
#### mock.js
mock 数据的配置文件。
### dist 目录
执行 `fes build` 后，产物默认会存放在这里。
### public 目录
此目录下所有文件会被 `copy` 到输出路径。
#### index.html
默认的 `html` 模板文件，如果删除此 `html` 则会使用内置的 `html` 模板文件。
### src 目录
#### .fes 目录
临时文件目录，比如入口文件、路由等，都会被临时生成到这里。不要提交 `.fes` 目录到 `git` 仓库，他们会在 `fes dev` 和 `fes build` 时被删除并重新生成。
#### pages 目录
所有路由组件存放在这里。
#### app.js
运行时配置文件，可以在这里扩展运行时的能力，比如修改路由等。

109
docs/guide/env.md Normal file
View File

@ -0,0 +1,109 @@
# 环境变量
## 设置环境变量
### 执行命令时添加
比如：
```bash
# OS X, Linux
PORT=3000 umi dev
# Windows (cmd.exe)
set PORT=3000 && umi dev
```
如果要同时考虑 OS X 和 Windows，可借助三方工具 [cross-env](https://github.com/kentcdodds/cross-env)
<CodeGroup>
<CodeGroupItem title="YARN" active>
```bash
yarn add cross-env --dev
cross-env PORT=3000 umi dev
```
</CodeGroupItem>
<CodeGroupItem title="NPM">
```bash
npm i cross-env --save-dev
cross-env PORT=3000 umi dev
```
</CodeGroupItem>
</CodeGroup>
### 在 .env 文件中定义
Fes.js 中约定根目录下以 `.env` 开头的文件为环境变量配置文件。
比如：
```bash
PORT=3000
```
然后执行
```bash
fes dev
```
会以 3000 端口启动 dev server。
#### 本地临时配置
可以新建 `.env.local`，这份配置会和 `.env` 做 `merge` 后形成最终配置。
#### 多环境多份配置
可以通过环境变量 `FES_ENV` 区分不同环境来指定配置，这时候必须在执行命令前添加 `FES_ENV` 保证执行加载环境变量配置文件逻辑前 `FES_ENV` 已设置。
举个 🌰 ：
```bash
FES_ENV=sit umi dev
```
如果存在 `.env.sit` 文件，则会将 `.env.sit` 的配置和 `.env` 做 `merge` 后形成最终配置。
#### 配置优先级
临时配置 > 环境配置 > .env
::: tip
如果两份配置中存在相同的项，则优先级高的会覆盖优先级低的。
:::
## 环境变量列表
### FES_ENV
指定当前的环境，不同环境各自的配置文件。
### FES_PRESETS
添加额外的插件集入口
### FES_PLUGINS
添加额外的插件入口
### PORT
`fes dev` 时服务指定的端口号，默认是 `8080`
### HOST
默认是 `localhost`。
### HTTPS
默认是 `false`。
### WATCH
设为 none 时不监听文件变更。比如：
```
WATCH=none fes dev
```
### BABEL_CACHE
默认开启 Babel 编译缓存，值为 none 时禁用缓存。
### ANALYZE
用于分析 bundle 构成，默认关闭。
比如：
```
ANALYZE=1 fes build
```
### ANALYZE_MODE
默认是`server`
### ANALYZE_PORT
默认是`8888`

1
docs/guide/faq.md Normal file
View File

@ -0,0 +1 @@
# 常见问题

189
docs/guide/getting-started.md
View File

@ -1,29 +1,43 @@
# Getting Started
## Prerequisites
- [Node.js v12+](https://nodejs.org/)
- [Yarn v1 classic](https://classic.yarnpkg.com/en/) (Optional)
## Manual Installation
This section will help you build a basic VuePress documentation site from ground up. If you already have an existing project and would like to keep documentation inside the project, start from Step 3.
- **Step 1**: Create and change into a new directory
# 快速上手
## 依赖环境
首先得有 [Node.js](https://nodejs.org/)，并确保 node 版本是 10.13 或以上。
```bash
mkdir vuepress-starter
cd vuepress-starter
# 打印 node 版本
node -v
v10.13.0
```
推荐使用 yarn 管理 npm 依赖
```bash
# 全局安装 yarn
npm i yarn -g
```
- **Step 2**: Initialize your project
## 安装模板
这一章节会帮助你从头搭建一个简单的 Fes.js 前端应用。
##### 步骤1 创建工作空间
如果不存在，则创建
```bash
# 创建目录 workspace
mkdir workspace
# 进入目录 workspace
cd workspace
```
如果已存在工作空间，则直接进入
```bash
# 进入目录 workspace
cd workspace
```
##### 步骤2 创建模板
<CodeGroup>
<CodeGroupItem title="YARN" active>
```bash
git init
yarn init
# 创建模板
yarn create @fesjs/fes-app myapp
```
</CodeGroupItem>
@ -31,20 +45,30 @@ yarn init
<CodeGroupItem title="NPM">
```bash
git init
npm init
# 创建模板
npx @fesjs/create-fes-app myapp
```
</CodeGroupItem>
</CodeGroup>
- **Step 3**: Install VuePress locally
如果项目目录 `workspace/myapp` 已经存在，则会提示目录已存在，你可以选择 `Overwrite` 删除目录后重新创建项目，也可以选择 `Merge` 使用模板文件覆盖当前目录文件。
![目录已存在提示](/pickTemplateTip.png)
如果项目目录 `workspace/myapp` 不存在，你会被提示选取一个 template。你可以选默认适用于中后台前端应用的 `PC` 类型，也可以选适用于移动端的 `H5` 类型。
![选择模板类型](/pickTemplate.png)
##### 步骤3 安装依赖
<CodeGroup>
<CodeGroupItem title="YARN" active>
```bash
yarn add -D vuepress@next
# 进入项目目录
cd myapp
# 安装依赖
yarn
```
</CodeGroupItem>
@ -52,43 +76,31 @@ yarn add -D vuepress@next
<CodeGroupItem title="NPM">
```bash
npm install -D vuepress@next
# 进入项目目录
cd myapp
# 安装依赖
npm i
```
</CodeGroupItem>
</CodeGroup>
- **Step 4**: Add some [scripts](https://classic.yarnpkg.com/en/docs/package-json#toc-scripts) to `package.json`
```json
{
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
}
}
```
- **Step 5**: Add the default temp and cache directory to `.gitignore` file
```bash
echo 'node_modules\n.temp\n.cache' >> .gitignore
```
- **Step 6**: Create your first document
```bash
mkdir docs
echo '# Hello VuePress' > docs/README.md
```
- **Step 7**: Serve the documentation site in the local server
## 启动项目
<CodeGroup>
<CodeGroupItem title="YARN" active>
```bash
yarn docs:dev
# 开发调试
yarn dev
yarn run v1.22.4
$ fes dev
Starting the development server http://localhost:8080 ...
✔ Webpack
Compiled successfully in 15.91s
DONE Compiled successfully in 15917ms 11:17:08 AM
```
</CodeGroupItem>
@ -96,12 +108,85 @@ yarn docs:dev
<CodeGroupItem title="NPM">
```bash
npm run docs:dev
# 开发调试
npm run dev
> @fesjs/fes-template@2.0.0-alpha.1 dev /Users/harrywan/company/git/fes.js/packages/fes-template
> fes dev
Starting the development server http://localhost:8080 ...
✔ Webpack
Compiled successfully in 3.66s
DONE Compiled successfully in 3662ms 11:17:46 AM
```
</CodeGroupItem>
</CodeGroup>
VuePress will start a hot-reloading development server at [http://localhost:8080](http://localhost:8080). When you modify your markdown files, the content in the browser will be auto updated.
By now, you should have a basic but functional VuePress documentation site. Next, learn about the basics of [configuration](./configuration.md) in VuePress.
Fes.js 会在 [http://localhost:8080](http://localhost:8080) 启动一个热重载的开发服务器。当你修改你的 .vue 文件时，浏览器中的内容也会自动更新。
![home](/home.png)
## 部署发布
### 构建
<CodeGroup>
<CodeGroupItem title="YARN" active>
```bash
# 构建
yarn build
yarn run v1.22.4
$ fes build
✔ Webpack
Compiled successfully in 45.37s
✨ Done in 48.87s.
```
</CodeGroupItem>
<CodeGroupItem title="NPM">
```bash
# 构建
npm run build
> @fesjs/fes-template@2.0.0-alpha.1 build /Users/harrywan/company/git/fes.js/packages/fes-template
> fes build
✔ Webpack
Compiled successfully in 45.37s
```
</CodeGroupItem>
</CodeGroup>
构建产物默认生成到 ./dist 下，然后通过 tree 命令查看。
```base
tree ./dist
dist
├── chunk-vendors.27cd4686.js
├── chunk-vendors.a5f5de67.css
├── index.11411d43.css
├── index.d72f1ba2.js
├── index.html
├── logo.png
└── static
└── logo.0f85bba0.png
```
### 本地验证
发布之前，可以通过 [serve](https://github.com/vercel/serve) 做本地验证，验证结果应该跟执行 `dev` 的结果一样。
### 部署
本地验证完，就可以部署了。你需要把 dist 目录部署到服务器上。

70
docs/guide/i18n.md
View File

@ -1,70 +0,0 @@
# I18n
## Site I18n Config
To take advantage of multi-language support in VuePress, you first need to use the following file and directory structure:
```
docs
├─ README.md
├─ foo.md
├─ nested
│  └─ README.md
└─ zh
├─ README.md
├─ foo.md
└─ nested
   └─ README.md
```
Then, specify the `locales` option in your [config file](./configuration.md#config-file):
```js
module.exports = {
locales: {
// The key is the path for the locale to be nested under.
// As a special case, the default locale can use '/' as its path.
'/': {
lang: 'en-US',
title: 'VuePress',
description: 'Vue-powered Static Site Generator',
},
'/zh/': {
lang: 'zh-CN',
title: 'VuePress',
description: 'Vue 驱动的静态网站生成器',
},
},
}
```
If a locale does not have a `lang`, `title`, `description` or `head`, VuePress will fallback to the root-level values. You can omit the root level config as long as they are provided in each locale.
::: tip
Config reference: [locales](../reference/config.md#locales)
:::
## Theme I18n Config
VuePress does not restrict how themes provide multi-language support, so each theme may have different way to handle i18n, and some themes may not provide multi-language support at all. You'd better refer to the theme documentation for detailed guide.
If you are using default theme, the multi-language support is the same with above:
```js
module.exports = {
themeConfig: {
locales: {
'/': {
selectLanguageName: 'English',
},
'/zh/': {
selectLanguageName: '简体中文',
},
},
},
}
```
::: tip
Config reference: [Default Theme > locales](../reference/default-theme/config.md#locales)
:::

366
docs/guide/markdown.md
View File

@ -1,366 +0,0 @@
# Markdown
Make sure you have known Markdown well before reading this section. If not, please learn some [Markdown tutorials](https://commonmark.org/help/) first.
## Syntax Extensions
The Markdown content in VuePress will be parsed by [markdown-it](https://github.com/markdown-it/markdown-it), which supports [syntax extensions](https://github.com/markdown-it/markdown-it#syntax-extensions) via markdown-it plugins.
This section will introduce built-in Markdown syntax extensions of VuePress.
You can also configure those built-in extensions, load more markdown-it plugins and implement your own extensions via [markdown](../reference/config.md#markdown) option and [extendsMarkdown](../reference/plugin-api.md#extendsmarkdown) option.
### Embedded
Embedded by markdown-it:
- [Tables](https://help.github.com/articles/organizing-information-with-tables/) (GFM)
- [Strikethrough](https://help.github.com/articles/basic-writing-and-formatting-syntax/#styling-text) (GFM)
### Header Anchors
You might have noticed that, a `#` anchor is displayed when you hover the mouse on the headers of each section. By clicking the `#` anchor, you can jump to the section directly.
::: tip
This header anchors extension is supported by [markdown-it-anchor](https://github.com/valeriangalliat/markdown-it-anchor).
Config reference: [markdown.anchor](../reference/config.md#markdown-anchor)
:::
### Links
When using Markdown [link syntax](https://spec.commonmark.org/0.29/#link-reference-definitions), VuePress will implement some conversions for you.
Take our documentation source files as an example:
```bash
└─ docs
├─ guide
│ ├─ getting-started.md
│ ├─ markdown.md # <- Here we are
│ └─ README.md
├─ reference
│ └─ config.md
└─ README.md
```
**Raw Markdown**
```md
[Home](/README.md)
[Guide](/guide/)
[Getting Started](./getting-started.md)
[markdown.links](../reference/config.md#links)
[GitHub](https://github.com)
```
**Converted to**
```vue
<RouterLink to="/">Home</RouterLink>
<RouterLink to="/guide/">Guide</RouterLink>
<RouterLink to="/guide/getting-started.html">Getting Started</RouterLink>
<RouterLink to="/reference/config.html#links">markdown.links</RouterLink>
<a href="https://github.com" target="_blank" rel="noopener noreferrer">GitHub<OutboundLink/></a>
```
**Rendered as**
[Home](/README.md)
[Guide](/guide/)
[Getting Started](./getting-started.md)
[markdown.links](../reference/config.md#links)
[GitHub](https://github.com)
**Explanation**
- Internal links will be converted to `<RouterLink>` for SPA navigation.
- Internal links to `.md` files will be converted to the [page route path](./page.md#routing), and both absolute path and relative path are supported.
- External links will get `target="_blank" rel="noopener noreferrer"` attrs and a <OutboundLink /> indicator.
::: tip
This links extension is supported by our built-in plugin.
Config reference: [markdown.links](../reference/config.md#markdown-links)
Also see: [Built-in Components > OutboundLink](../reference/components.md#outboundlink)
:::
### Emoji :tada:
You can add emoji to your Markdown content by typing `:EMOJICODE:`.
For a full list of available emoji and codes, check out [emoji-cheat-sheet.com](https://emoji-cheat-sheet.com/).
**Input**
```md
VuePress 2 is out :tada: !
```
**Output**
VuePress 2 is out :tada: !
::: tip
This emoji extension is supported by [markdown-it-emoji](https://github.com/markdown-it/markdown-it-emoji).
Config reference: [markdown.emoji](../reference/config.md#markdown-emoji)
:::
### Table of Contents
If you want to put the table of contents (TOC) of your current page inside your Markdown content, you can use the `[[toc]]` syntax.
**Input**
```md
[[toc]]
```
**Output**
[[toc]]
The headers in TOC will link to the corresponding [header anchors](#header-anchors), so TOC won't work well if you disable header anchors.
::: tip
This toc extension is supported by our built-in plugin, which is forked and modified from [markdown-it-toc-done-right](https://github.com/nagaozen/markdown-it-toc-done-right).
Config reference: [markdown.toc](../reference/config.md#markdown-toc)
:::
### Code Blocks
Following code blocks extensions are implemented during markdown parsing in Node side. That means, the code blocks won't be processed in client side.
If you want to implement client-side syntax highlighting via [prism.js](https://prismjs.com/#basic-usage) or [highlight.js](https://highlightjs.org/), you could disable our code blocks extensions, and introduce your library manually in client side.
#### Syntax Highlighting
VuePress uses [Prism](https://prismjs.com/) to highlight language syntax in Markdown code blocks, using coloured text.
Prism supports a wide variety of programming languages. For a full list of available languages, check out [Prism supported languages](https://prismjs.com/#supported-languages).
You can add an optional language identifier to enable syntax highlighting in your fenced code blocks:
**Input**
````md
```ts
import type { UserConfig } from '@vuepress/cli'
export const config: UserConfig = {
title: 'Hello, VuePress',
}
```
````
**Output**
```ts
import type { UserConfig } from '@vuepress/cli'
export const config: UserConfig = {
title: 'Hello, VuePress',
}
```
::: tip
This syntax highlighting extension is supported by our built-in plugin.
Config reference: [markdown.code.highlight](../reference/config.md#markdown-code-highlight)
:::
#### Line Highlighting
You can highlight specified lines of your code blocks by adding line ranges mark in your fenced code blocks:
**Input**
````md
```ts{1,6-8}
import type { UserConfig } from '@vuepress/cli'
export const config: UserConfig = {
title: 'Hello, VuePress',
themeConfig: {
logo: 'https://vuejs.org/images/logo.png',
},
}
```
````
**Output**
```ts{1,6-8}
import type { UserConfig } from '@vuepress/cli'
export const config: UserConfig = {
title: 'Hello, VuePress',
themeConfig: {
logo: 'https://vuejs.org/images/logo.png',
},
}
```
Examples for line ranges mark:
- Line ranges: `{5-8}`
- Multiple single lines: `{4,7,9}`
- Combined: `{4,7-13,16,23-27,40}`
::: tip
This line highlighting extension is supported by our built-in plugin, which is forked and modified from [markdown-it-highlight-lines](https://github.com/egoist/markdown-it-highlight-lines).
Config reference: [markdown.code.highlightLines](../reference/config.md#markdown-code-highlightlines)
:::
#### Line Numbers
You must have noticed that the number of lines is displayed on the left side of code blocks. This is enabled by default and you can disable it in config.
You can add `:line-numbers` / `:no-line-numbers` mark in your fenced code blocks to override the value set in config.
**Input**
````md
```ts
// line-numbers is enabled by default
const line2 = 'This is line 2'
const line3 = 'This is line 3'
```
```ts:no-line-numbers
// line-numbers is disabled
const line2 = 'This is line 2'
const line3 = 'This is line 3'
```
````
**Output**
```ts
// line-numbers is enabled by default
const line2 = 'This is line 2'
const line3 = 'This is line 3'
```
```ts:no-line-numbers
// line-numbers is disabled
const line2 = 'This is line 2'
const line3 = 'This is line 3'
```
::: tip
This line numbers extension is supported by our built-in plugin.
Config reference: [markdown.code.lineNumbers](../reference/config.md#markdown-code-linenumbers)
:::
#### Wrap with v-pre
As [template syntax is allowed in Markdown](#template-syntax), it would also work in code blocks, too.
To avoid your code blocks being compiled by Vue, VuePress will add [v-pre](https://v3.vuejs.org/api/directives.html#v-pre) directive to your code blocks by default, which can be disabled in config.
You can add `:v-pre` / `:no-v-pre` mark in your fenced code blocks to override the value set in config.
::: warning
The template syntax characters, for example, the "Mustache" syntax (double curly braces) might be parsed by the syntax highlighter. Thus, as the following example, `:no-v-pre` might not work well in some languages.
If you want to make Vue syntax work in those languages anyway, try to disable the default syntax highlighting and implement your own syntax highlighting in client side.
:::
**Input**
````md
```md
<!-- This will be kept as is by default -->
1 + 2 + 3 = {{ 1 + 2 + 3 }}
```
```md:no-v-pre
<!-- This will be compiled by Vue -->
1 + 2 + 3 = {{ 1 + 2 + 3 }}
```
```js:no-v-pre
// This won't be compiled correctly because of js syntax highlighting
const onePlusTwoPlusThree = {{ 1 + 2 + 3 }}
```
````
**Output**
```md
<!-- This will be kept as is -->
1 + 2 + 3 = {{ 1 + 2 + 3 }}
```
```md:no-v-pre
<!-- This will be compiled by Vue -->
1 + 2 + 3 = {{ 1 + 2 + 3 }}
```
```js:no-v-pre
// This won't be compiled correctly because of js syntax highlighting
const onePlusTwoPlusThree = {{ 1 + 2 + 3 }}
```
::: tip
This v-pre extension is supported by our built-in plugin.
Config reference: [markdown.code.vPre](../reference/config.md#markdown-vpre)
:::
## Using Vue in Markdown
This section will introduce some basic usage of Vue in Markdown.
Check out [Advanced > Markdown and Vue SFC](./advanced/markdown.md) for more details.
### Template Syntax
As we know:
- HTML is allowed in Markdown.
- Vue template syntax is compatible with HTML.
That means, [Vue template syntax](https://v3.vuejs.org/guide/template-syntax.html) is allowed in Markdown.
**Input**
```md
One plus one equals: {{ 1 + 1 }}
<span v-for="i in 3"> span: {{ i }} </span>
```
**Output**
One plus one equals: {{ 1 + 1 }}
<span v-for="i in 3"> span: {{ i }} </span>
### Components
You can use Vue components directly in Markdown.
**Input**
```md
This is default theme built-in `<Badge />` component <Badge text="demo" />
```
**Output**
This is default theme built-in `<Badge />` component <Badge text="demo" />
::: tip
Check out the [Built-in Components](../reference/components.md) for a full list of built-in components.
Check out the [Default Theme > Built-in Components](../reference/default-theme/components.md) for a full list of default theme built-in components.
:::

183
docs/guide/mock.md Normal file
View File

@ -0,0 +1,183 @@
# Mock 数据
Mock 数据是前端开发过程中必不可少的一环，是分离前后端开发的关键链路。通过预先跟服务器端约定好的接口，模拟请求数据甚至逻辑，能够让前端开发独立自主，不会被服务端的开发所阻塞。
## 约定式 Mock 文件
Fes.js 约定 `src/mock.js` 为 mock 文件。
比如：
```
.
├── mock.js
└── src
└── pages
└── index.vue
```
## 编写 Mock 文件
可以参考如下例子：
``` js
module.exports = function ({ cgiMock, mockjs, utils }) {
const { Random } = mockjs;
// 测试 proxy 与 mock 用例集合
cgiMock('/movie/in_theaters_mock', (req, res) => {
res.send(JSON.stringify({
code: '0',
msg: '',
result: {
text: 'movie: movie/in_theaters_mock ~~~~~'
}
}));
});
cgiMock('/movie/test_mock', (req, res) => {
res.send(JSON.stringify({
code: '0',
msg: '',
result: {
text: 'mock: movie/test_mock'
}
}));
});
// 测试用例: mock.js change，重现请求，需要能拉最新的数据
cgiMock('/watchtest', (req, res) => {
res.send(JSON.stringify({
code: '0',
msg: '',
result: {
text: '通过 register 测试 mock watch: 初始状态'
}
}));
});
// 返回一个数字
// cgiMock('/number', 666);
cgiMock('/number', 999);
// 返回一个json
cgiMock({
url: '/json',
result: {
code: '400101', msg: "不合法的请求:Missing cookie 'wb_app_id' for method parameter of type String", transactionTime: '20170309171146', success: false
}
});
// 利用 mock.js 产生随机文本
cgiMock('/text', Random.cparagraph());
// 返回一个字符串 利用 mock.js 产生随机字符
cgiMock('/random', mockjs.mock({
'string|1-10': '★'
}));
// 正则匹配url, 返回一个字符串
cgiMock(/\/abc|\/xyz/, 'regexp test!');
// option.result 参数如果是一个函数, 可以实现自定义返回内容, 接收的参数是是经过 express 封装的 req 和 res 对象.
cgiMock(/\/function$/, (req, res) => {
res.send('function test');
});
// 返回文本 readFileSync
cgiMock('/file', utils.file('./package.json'));
// 更复杂的规则配置
cgiMock({
url: /\/who/,
method: 'GET',
result(req, res) {
if (req.query.name === 'kwan') {
res.json({ kwan: '孤独患者' });
} else {
res.send('Nooooooooooo');
}
},
headers: {
'Content-Type': 'text/plain',
'Content-Length': '123',
ETag: '12345'
},
cookies: [
{
name: 'myname', value: 'kwan', maxAge: 900000, httpOnly: true
}
]
});
// 携带参数的请求
cgiMock('/v2/audit/list', (req, res) => {
const {
currentPage, pageSize, isAudited
} = req.body;
res.send({
code: '0',
msg: '',
data: {
currentPage,
pageSize,
totalPage: 2,
totalCount: 12,
pageData: Array.from({ length: pageSize }, () => ({
title: Random.title(),
authorName: Random.cname(),
authorId: Random.name(),
createTime: Date.now(),
updateTime: Date.now(),
readCount: Random.integer(60, 1000),
favoriteCount: Random.integer(1, 50),
postId: '12323',
serviceTag: '业务类型',
productTag: '产品类型',
requestTag: '需求类型',
handleTag: '已采纳',
postType: 'voice',
postStatus: isAudited ? 'pass' : 'auditing',
auditStatus: 'audit1'
}))
}
});
});
// multipart/form-data 类型
cgiMock('/v2/upload', (req, res) => {
res.send({
code: '0',
msg: '文件上传成功'
});
});
};
```
### cgiMock 参数
创建一个 mock 接口，参数非常灵活，参考上面的 demo 即可。
### mockjs 参数
[Mock.js](http://mockjs.com/) 是常用的辅助生成模拟数据的三方库，借助他可以提升我们的 mock 数据能力。
比如：
```js
module.exports = function ({ cgiMock, mockjs, utils }) {
cgiMock('/random', mockjs.mock({
'string|1-10': '★'
}));
}
```
### utils 参数
工具函数：
- utils.file(path)，从项目根目录根据path寻找文件，返回文件流。
## 配置 Mock
详见配置 #mock。
## 关闭 Mock
可以通过配置关闭。
```js
export default {
mock: false,
};
```

55
docs/guide/page.md
View File

@ -1,55 +0,0 @@
# Page
VuePress is markdown-centered. Each markdown file inside your project is a standalone page.
## Routing
By default, the route path of a page is determined by the relative path of your markdown file.
Assuming this is the directory structure of your markdown files:
```
└─ docs
├─ guide
│ ├─ getting-started.md
│ └─ README.md
├─ contributing.md
└─ README.md
```
Take the `docs` directory as your [sourceDir](../reference/cli.md), e.g. your are running `vuepress dev docs` command. Then the route paths of your markdown files would be:
| Relative Path | Route Path |
|--------------------|----------------------|
| `/README.md` | `/` |
| `/contributing.md` | `/contributing.html` |
| `/guide/README.md` | `/guide/` |
| `/guide/page.md` | `/guide/page.html` |
## Frontmatter
A markdown file could contain a [YAML](https://yaml.org/) frontmatter. The frontmatter must be at the top of the Markdown file and must be wrapped with a couple of triple-dashed lines. Here is a basic example:
```md
---
lang: en-US
title: Title of this page
description: Description of this page
---
```
You must have noticed that those fields are similar with the [Site Config](./configuration.md#site-config) of in the [Config File](./configuration.md#config-file). You can override `lang`, `title`, `description`, etc., of current page via frontmatter. So you can take frontmatter as page scope config.
Also, VuePress has built-in support for some frontmatter fields, and your theme may have its own special frontmatter, too.
::: tip
Check out the [Frontmatter Reference](../reference/frontmatter.md) for a full list of VuePress built-in frontmatter.
Check out the [Default Theme > Frontmatter Reference](../reference/default-theme/frontmatter.md) for the frontmatter of default theme.
:::
## Content
The main content of your page is written in Markdown. VuePress will firstly transform your Markdown to HTML code, then treat the HTML code as `<template>` of Vue SFC.
With the power of [markdown-it](https://github.com/markdown-it/markdown-it) and Vue template syntax, the basic Markdown can be extended a lot. Next, check out the [Markdown](./markdown.md) guide for all the extensions of Markdown in VuePress.

92
docs/guide/plugin.md
View File

@ -1,45 +1,71 @@
# Plugin
# 插件
With the help of [Plugin API](../references/plugin-api.md), VuePress plugin can provide different features for you.
## 插件的 id 和 key
每个插件都会对应一个 `id` 和一个 `key`，**`id` 是路径的简写，`key` 是进一步简化后用于配置的唯一值**。
## Community Plugin
比如插件 `/node_modules/@fesjs/plugin-foo/index.js`，通常来说，其 `id` 为 `@fesjs/plugin-foo`，`key` 为 `foo`。
Community users have created lots of plugins and published them to [NPM](https://www.npmjs.com/search?q=keywords:vuepress-plugin). VuePress team also maintains some official plugins under the [@vuepress](https://www.npmjs.com/search?q=%40vuepress%20keywords%3Aplugin) scope. You should check the plugin's own documentation for detailed guide.
::: tip
id 一般用不上，对于普通开发者 key 用来配置插件，而插件开发者可以使用 key 判断是否安装某个插件。
:::
In general, you need to specify the name of the plugin to use in [plugins](../reference/plugin-api.md#plugins) option:
## 启动插件
有多种方式引入插件
```js
module.exports = {
plugins: [
'foo',
['bar', { /* options */ }]
],
### package.json 依赖
Fes.js 会自动检测 `dependencies` 和 `devDependencies` 里的 fes 插件，比如：
```json
{
"dependencies": {
"@fesjs/plugin-request": "^2.0.0"
}
}
```
那么 `@fesjs/plugin-request` 会自动被注册，无需在配置里重复声明。
You can use either plugin name or its shorthand:
| Plugin Name | Shorthand |
|---------------------------|---------------------|
| `vuepress-plugin-foo` | `foo` |
| `@org/vuepress-plugin-bar`| `@org/bar` |
| `@vuepress/plugin-foobar` | `@vuepress/foobar` |
## Local Plugin
If you want to use your own plugin but don't want to publish it, you can create a local plugin.
It is recommended to use the [Config File](./configuration.md#config-file) directly as a plugin, because [almost all of the Plugin APIs are available](../reference/config.md#plugin-api), which would be more convenient in most cases.
But if you have too many things to do in your config file, it's better to extract them into separate plugins, and use them by setting the absolute path to them or requiring them:
### 配置
在配置里可通过 `presets` 和 `plugins` 配置插件，比如：
```js
module.exports = {
plugins: [
'/path/to/your-plugin.js',
require('./another-plugin'),
],
export default {
presets: ['./preset', 'foo/presets'],
plugins: ['./plugin'],
}
```
通常用于几种情况：
You can refer to [Advanced > Writing a Plugin](./advanced/plugin.md) for how to write your own plugin.
1. 项目相对路径的插件
2. 非 npm 包入口文件的插件
::: warning
请不要配置 npm 包的插件，否则会报重复注册的错误
:::
### 环境变量
还可通过环境变量 `FES_PRESETS` 和 `FES_PLUGINS` 注册额外插件。
比如：
```bash
FES_PRESETS=/a/b/preset.js fes dev
```
## 禁用插件
通过配置插件的 `key` 为 `false`，比如：
```js
export default {
mock: false,
}
```
Mock 插件的 `key` 是 `mock`，我们在配置文件中配置 `mock` 为 `false`，则会禁用 Mock 插件及其功能。
## 配置插件
通过插件的 `key` 来配置插件，比如：
```js
export default {
mock: {
prefix: '/v2'
}
}
```
这里的 `mock` 是 Mock插件 的 key。

259
docs/guide/route.md Normal file
View File

@ -0,0 +1,259 @@
# 路由
像 Vue 、React 这类框架是用组件化搭建页面，路由解决的是路径到组件的匹配问题。Fes.js 基于 `Vue Router` 实现的路由，想了解更多的同学可以看看[官方文档](https://next.router.vuejs.org/)。
## 路由配置
在配置文件 `.fes.js`中通过 `router` 进行配置。
```js
export default {
router: {
routes: [],
mode: 'hash'
}
}
```
### routes
`routes` 是配置添加到路由的初始路由列表，格式为路由信息的数组。具体使用参考 [Vue Router 文档](https://next.router.vuejs.org/zh/guide/) 中关于路由配置、路由匹配相关内容。
### mode
创建历史记录的类型：
- **h5**，对应 [createWebHistory](https://next.router.vuejs.org/zh/api/#createwebhistory)
- **hash**，对应 [createWebHashHistory](https://next.router.vuejs.org/zh/api/#createWebHashHistory)
- **memory**，对应 [createMemoryHistory](https://next.router.vuejs.org/zh/api/#createWebHashHistory)
## 约定式路由
约定式路由也叫文件路由，就是不需要手写配置，文件系统即路由，通过目录和文件及其命名分析出路由配置。
### 约定规范
比如以下文件结构：
```
pages
├── index.vue # 根路由页面 路径为 /
├── *.vue # 模糊匹配 路径为 *
├── a.vue # 路径 /a
├── b # 文件夹b
│ ├── index.vue # 路径 /b
│ ├── @id.vue # 动态路由 /b/:id
│ ├── c.vue # 路径 /b/c
│ └── layout.vue # /b 路径下所有页面公共的布局组件
└── layout.vue # 根路由下所有页面共用的布局组件
```
编译后会得到以下路由配置：
```js
[
{
"path": "/",
"component": require('@/pages/layout').default,
"count": 5,
"children": [
{
"path": "/a",
"component": require('@/pages/a').default,
"name": "a",
"meta": {},
"count": 7
},
{
"path": "/b",
"component": require('@/pages/b/layout').default,
"count": 7,
"children": [
{
"path": "/b/c",
"component": require('@/pages/b/c').default,
"name": "b_c",
"meta": {},
"count": 14
},
{
"path": "/b/:id",
"component": require('@/pages/b/@id').default,
"name": "b__id",
"meta": {},
"count": 13
},
{
"path": "/b",
"component": require('@/pages/b/index').default,
"name": "b_index",
"meta": {},
"count": 7
}
]
},
{
"path": "/",
"component": require('@/pages/index').default,
"name": "index",
"meta": {},
"count": 5
},
{
"path": "/:pathMatch(.*)",
"component": require('@/pages/*').default,
"name": "FUZZYMATCH",
"meta": {},
"count": 3
}
]
}
]
```
**需要注意的是，满足以下任意规则的文件不会被注册为路由**：
- 不是 `.vue` 文件
- `components` 目录中的文件
### 动态路由
Fes.js 里约定以 `@` 开头的文件或文件夹映射为动态路由。
比如：
- `src/pages/users/@id.vue` 会成为 `/users/:id`
- `src/pages/users/@id/settings.vue` 会成为 `/users/:id/settings`
### 嵌套路由
Fes.js 里约定目录下有 `layout.vue` 时会生成嵌套路由，以 `layout.vue` 为该目录的公共父组件，`layout.vue` 中必须实现 `RouterView`
比如以下目录结构：
```
pages
└── users
├── layout.vue
├── index.vue
└── list.vue
```
会生成路由：
```js
[
{
path: '/users', component: require('@/pages/users/layout').default,
children: [
{ path: '/users', component: require('@/pages/users/index').default },
{ path: '/users/list', component: require('@/pages/users/list').default },
]
}
]
```
### 模糊匹配
Fes.js 下约定文件名为 `*` 的路由是模糊匹配路由，可以用此特性实现 [404 路由](https://next.router.vuejs.org/zh/guide/essentials/dynamic-matching.html#%E6%8D%95%E8%8E%B7%E6%89%80%E6%9C%89%E8%B7%AF%E7%94%B1%E6%88%96-404-not-found-%E8%B7%AF%E7%94%B1)。
比如以下目录结构：
```
pages
├── index.vue # 根路由页面 路径为 /
└── *.vue # 模糊匹配 路径为 *
```
会生成路由：
```js
[
{
path: '/', component: require('@/pages/index').default, count: 5
},
{
path: '/:pathMatch(.*)', component: require('@/pages/**').default, count: 3
}
]
```
这样，如果访问 `/foo`，`/` 不能匹配，会 fallback 到 `*` 路由，通过 `src/pages/*.vue` 进行渲染。
### 扩展路由元信息
我们在定义路由时可以配置`meta`字段，用来记录一些跟路由相关的信息：
```js
const router = new VueRouter({
routes: [
{
path: '/foo',
component: Foo,
children: [
{
path: 'bar',
component: Bar,
// a meta field
meta: { requiresAuth: true }
}
]
}
]
})
```
在 Fes.js 里约定在 `.vue` 文件中的 `config` 为 `meta` 配置。如果 `pages/a.vue` 中有如下配置：
```vue
<config>
{
"name": "store",
"title": "vuex测试"
}
</config>
```
则编译后的路由配置为：
```js{5-8}
[
{
path: '/a',
component: require('@/pages/a').default,
meta: {
"name": "store",
"title": "vuex测试"
}
},
]
```
### 智能路由
可以看到，编译后路由都会有 `count` 属性，这是我们根据精准匹配优先算法原则设计出路由排名算法，对匹配到的路由打分：
- 路由的路径每个子项得到4分
- 子项为静态细分(`/list`)再加3分
- 子项为动态细分（`/:orderId`）再加2分
- 根段(`/`)再1分
- 通配符(`*`)匹配到的减去1分
当我们跳转路由时，如果 URL 匹配到多个路由，则选择分数最高的路由。
## 路由跳转
想学习更多，可以查看 [Vue Router 官方文档](https://next.router.vuejs.org/zh/guide/essentials/navigation.html#%E6%9B%BF%E6%8D%A2%E5%BD%93%E5%89%8D%E4%BD%8D%E7%BD%AE)。
### 声明式
```vue
<template>
<router-link to="/home">Home</router-link>
</template>
```
### 命令式
页面跳转 API 由 `router` 实例提供，查看 [Vue Rouer 文档](https://next.router.vuejs.org/zh/api/#router-%E6%96%B9%E6%B3%95)了解更多。
```js
import { useRouter } from '@fesjs/fes';
export default {
setup(){
const router = useRouter();
// 这三种形式是等价的
router.push('/users/posva#bio')
router.push({ path: '/users/posva', hash: '#bio' })
router.push({ name: 'users', params: { username: 'posva' }, hash: '#bio' })
// 只改变 hash
router.push({ hash: '#bio' })
// 只改变 query
router.push({ query: { page: '2' } })
// 只改变 param
router.push({ params: { username: 'jolyne' } })
// 跳转到上一个路由
router.goBack();
// 跳转到前一个历史记录
router.go(1);
// 替换历史堆栈中的记录
router.replace('/new');
}
}
```

53
docs/guide/template.md Normal file
View File

@ -0,0 +1,53 @@
# HTML模板
Fes.js 基于 [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin) 实现的模板功能，默认 HTML模板 是：
```html
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width,initial-scale=1.0">
<title><%= htmlWebpackPlugin.options.title %></title>
</head>
<body>
<div id="app"></div>
</body>
</html>
```
## 替换模板
在 `src/public` 文件夹中创建`index.html`，Fes.js 约定如果这个文件存在，则会替换默认模板。
## 配置模板
### 配置
在配置文件（`.fes.js`）中配置 `html`，把配置的对象作为参数传入 `html-webpack-plugin` 实例。
举个 :chestnut: ：
```js
export default {
html: {
title: '海贼王'
}
}
```
页面的 title 会设置成'海贼王'。
### 手动
当然我们也可以手动编写模板，在模板中添加`link`、`link`、`meta`等标签。在我们手动配置模板时，有时候需要用到一些环境变量，模板里可以获取到的变量如下：
- **htmlWebpackPlugin**，特定于此插件的数据
- **webpackConfig**，用于此编译的webpack配置。例如，它可用于获取publicPath（webpackConfig.output.publicPath）。
- **compilation**，webpack编译对象。例如，可以使用它来获取已处理资产的内容，并将其直接内联到页面中compilation.assets[...].source()
举个 🌰 ：
```html
<link rel="icon" type="image/x-icon" href="<%= webpackConfig.output.publicPath %>favicon.png" />
```
除上述 `html-webpack-plugin` 三点之外，Fes.js 还把 `process.env` 中所有环境变量都添加到了模板作用域内：
- `NODE_ENV`
- `FES_ENV`
- `.env` 文件中定义的以 `FES_APP_` 开头的变量

52
docs/guide/theme.md
View File

@ -1,52 +0,0 @@
# Theme
VuePress theme can provide layouts, styles and many other features for you, helping you to focus on writing Markdown content.
VuePress has a default theme out of the box, which is applied to our documentation site you are currently browsing. The default theme provides basic but useful features for documentation site, you can check out [Default Theme Config Reference](../reference/default-theme/config.md) for a full list of config.
However, you might think it is not good enough. Or, you want to build a different type of site, for example, a blog, instead of a documentation. Then, you can try to [use a community theme](#community-theme) or [create a local theme](#local-theme).
## Community Theme
Community users have created lots of theme and published them to [NPM](https://www.npmjs.com/search?q=keywords:vuepress-theme). You should check the theme's own documentation for detailed guide.
In general, you need to specify the name of the theme to use in [theme](../reference/config.md#theme) option:
```js
module.exports = {
theme: 'foo',
}
```
You can use either theme name or its shorthand:
| Theme Name | Shorthand |
|---------------------------|---------------------|
| `vuepress-theme-foo` | `foo` |
| `@org/vuepress-theme-bar` | `@org/bar` |
| `@vuepress/theme-default` | `@vuepress/default` |
## Local Theme
If you want to use your own custom theme but don't want to publish it, you can create a local theme.
First, create the local theme directory, typically `.vuepress/theme` :
```
└─ docs
├─ .vuepress
│ ├─ theme
│ │ └─ index.js
│ └─ config.js
└─ README.md
```
Then, set the absolute path of the theme directory to use it:
```js
module.exports = {
theme: '/path/to/docs/.vuepress/theme',
}
```
Next, refer to [Advanced > Writing a Theme](./advanced/theme.md) for how to write your own theme.

1
docs/reference/api.md Normal file
View File

@ -0,0 +1 @@
# API

182
docs/reference/api/README.md Normal file
View File

@ -0,0 +1,182 @@
---
sidebar: auto
---
# API
Fes.js 统一了API的出口，所有运行时API（包含Fes.js内置API和插件提供的API）全部通过`@fesjs/fes`导出。
```js
import { someApi } from "@fesjs/fes"
```
## 基础API
### plugin
::: tip
主要在插件里面使用，项目代码中一般用不到。
:::
运行时插件接口，是 Umi 内置的跑在浏览器里的一套插件体系。
```js
import { plugin, ApplyPluginsType } from 'umi';
// 注册插件
plugin.register({
apply: { dva: { foo: 1 } },
path: 'foo',
});
plugin.register({
apply: { dva: { bar: 1 } },
path: 'bar',
});
// 执行插件
// 得到 { foo: 1, bar: 1 }
plugin.applyPlugins({
key: 'dva',
type: ApplyPluginsType.modify,
initialValue: {},
args: {},
async: false,
});
```
#### **plugin.register** 参数包含:
- apply 插件文件导出的内容
- path 插件文件路径
#### **plugin.applyPlugins** 参数包含:
- key，坑位的 key
- type，执行方式类型，详见 [ApplyPluginsType](#applypluginstype)
- initialValue，初始值
- args，参数
- async，是否异步执行且返回 Promise
### ApplyPluginsType
::: tip
主要在插件里面使用，项目代码中一般用不到。
:::
运行时插件执行类型，enum 类型，包含三个属性：
- compose，用于合并执行多个函数，函数可决定前序函数的执行时机
- modify，用于修改值
- event，用于执行事件，前面没有依赖关系
## 路由API
Fes.js 路由基于 [Vue Router 4.0](https://next.router.vuejs.org/introduction.html)，想了解更多的同学可以看看官方文档。
### useRoute
返回当前 `route` 实例，相当于在模板内使用 `$route`。必须在 `setup` 函数内调用。
```js
import { useRoute } from "@fesjs/fes";
export default {
setup(){
const route = useRoute()
}
}
```
### useRouter
返回 `router` 实例，相当于在模板语法中使用 `$router`。必须在 `setup` 函数内调用。
```js
import { useRouter } from "@fesjs/fes";
export default {
setup(){
const router = useRouter()
}
}
```
### onBeforeRouteUpdate
添加导航守卫，在当前路由即将更新时触发。类似于之前的`beforeRouteUpdate`，但是可用于任何组件。卸载组件时，将移除守卫。
```js
import { onBeforeRouteUpdate } from "@fesjs/fes";
export default {
setup(){
onBeforeRouteUpdate((to, from, next)=>{
})
}
}
```
### onBeforeRouteLeave
添加导航守卫，在当前路由即将离开时触发。类似于之前的`beforeRouteLeave`，但可用于任何组件。卸载组件时，将移除守卫。
```js
import { onBeforeRouteLeave } from "@fesjs/fes";
export default {
setup(){
onBeforeRouteLeave((to, from, next)=>{
})
}
}
```
### createWebHashHistory
::: tip
在开发插件时可能用上，平时一般用不上
:::
创建一个 hash 历史记录。对于没有主机的 web 应用程序 (例如 file://)，或当配置服务器不能处理任意URL时这非常有用。注意：如果 SEO 对你很重要，你应该使用 `createWebHistory`。
### createWebHistory
::: tip
在开发插件时可能用上，平时一般用不上
:::
创建HTML5历史记录。单页应用程序最常见的历史记录。必须通过 http 服务打开页面地址 。
### createMemoryHistory
::: tip
在开发插件时可能用上，平时一般用不上
:::
创建一个基于内存的历史记录。这个历史记录的主要目的是处理 SSR。它在一个特殊的位置开始，这个位置无处不在。如果用户不在浏览器上下文中，它们可以通过调用 router.push() 或 router.replace() 将该位置替换为启动位置。
### createRouter
创建一个路由器实例，该实例可用于 Vue 应用程序。查看[路由器选项](https://next.router.vuejs.org/api/#routeroptions)，了解可以传递的所有属性的列表。
### RouterLink
使用自定义组件路由器链接来创建链接，而不是使用常规标签。这使得 Vue 路由器无需重新加载页面即可更改 URL、处理 URL 生成及其编码。
```html
<router-link to="/about">Go to About</router-link>
```
可以查看[官方文档](https://next.router.vuejs.org/api/#router-link-props)了解更多 RouterLink 的 Porps。查看[官方文档](https://next.router.vuejs.org/api/#router-link-s-v-slot)了解 RouterLink 的作用域插槽。
### useLink
返回的结果跟 RouterLink 的作用域插槽的属性一致，查看[官方API](https://next.router.vuejs.org/api/#router-link-s-v-slot)了解更多。
```js
import { RouterLink, useLink } from '@fesjs/fes'
export default {
name: 'AppLink',
props: {
// add @ts-ignore if using TypeScript
...RouterLink.props,
inactiveClass: String,
},
setup(props) {
// `props` contains `to` and any other prop that can be passed to <router-link>
const { navigate, href, route, isActive, isExactActive } = useLink(props)
// profit!
return { isExternalLink }
},
}
```
### RouterView
router-view 将显示当前 URL 的对应的路由组件。你可以把它放在任何地方，以适应你的布局。
```html
<router-view></router-view>
<router-view v-slot="{ Component, route }">
<component :is="Component" />
</router-view>
```
可以查看[官方文档](https://next.router.vuejs.org/api/#router-view-props)了解更多 RouterView 的 Porps。查看[官方文档](https://next.router.vuejs.org/api/#router-view-s-v-slot)了解 RouterView 的作用域插槽。
### Router Methods
查看[官方文档](https://next.router.vuejs.org/api/#router-methods)了解更多

3
docs/reference/bundler/vite.md
View File

@ -1,3 +0,0 @@
# Vite
> TODO

3
docs/reference/bundler/webpack.md
View File

@ -1,3 +0,0 @@
# Webpack
> TODO

18
docs/reference/cli.md
View File

@ -1,8 +1,8 @@
# Command Line Interface
# 命令行接口
VuePress CLI is provided by [@vuepress/cli](https://www.npmjs.com/package/@vuepress/cli) package. It is a dependency of the [vuepress](https://www.npmjs.com/package/vuepress) package, and you can also install it separately.
VuePress 命令行接口是由 [@vuepress/cli](https://www.npmjs.com/package/@vuepress/cli) 包提供的。它是 [vuepress](https://www.npmjs.com/package/vuepress) 包的依赖之一，当然你也可以单独安装它。
Run `vuepress --help` to get following help messages:
执行 `vuepress --help` 来获取下列帮助信息：
```bash
Usage:
@ -25,7 +25,7 @@ Options:
## dev
Start a development server to develop your VuePress site locally.
启动一个开发服务器，在本地开发你的 VuePress 站点。
```bash
Usage:
@ -47,12 +47,12 @@ Options:
```
::: tip
Options set by CLI will override those options with the same name in your config file.
通过命令行设置的配置项，会覆盖你配置文件中的同名配置项。
:::
## build
Build your VuePress site to static files, which are ready for [deployment](../guide/deployment.md).
将你的 VuePress 站点构建成静态文件，以便你进行后续[部署](../guide/deployment.md)。
```bash
Usage:
@ -71,11 +71,11 @@ Options:
```
::: tip
Options set by CLI will override those options with the same name in your config file.
通过命令行设置的配置项，会覆盖你配置文件中的同名配置项。
:::
## info
Outputs information about your system and dependencies.
输出当前系统和依赖相关的信息。
This command would be helpful when you want to check your environment or report an issue.
在你想要检查你的环境，或者提交 Issue 时候，可以使用该命令。

175
docs/reference/cli/README.md Normal file
View File

@ -0,0 +1,175 @@
---
sidebar: auto
---
# 命令行工具
## create-fes-app
通过 `create-fes-app` 命令创建项目模板，输入`create-fes-app -h`则可以看到如下信息：
```
Usage: create-fes-app <name>
Options:
-v, --version Output the current version
-h, --help Display help for command
-f, --force Overwrite target directory if it exists
-m, --merge Merge target directory if it exists
```
可以在本机安装后使用：
<CodeGroup>
<CodeGroupItem title="YARN" active>
```bash
# 全局安装
yarn global add @fesjs/create-fes-app
# 创建模板
create-fes-app fes-app
```
</CodeGroupItem>
<CodeGroupItem title="NPM">
```bash
# 全局安装
npm i -g @fesjs/create-fes-app
# 创建模板
create-fes-app fes-app
```
</CodeGroupItem>
</CodeGroup>
推荐使用 `yarn create` 和 `npx` 方式创建模板，一直使用最新的模板：
<CodeGroup>
<CodeGroupItem title="YARN" active>
```bash
# 创建模板
yarn create @fesjs/fes-app myapp
# 安装依赖
yarn
# 运行
yarn dev
```
</CodeGroupItem>
<CodeGroupItem title="NPM">
```bash
# 创建模板
npx @fesjs/create-fes-app myapp
# 安装依赖
npm install
# 运行
npm run dev
```
</CodeGroupItem>
</CodeGroup>
## fes
需要在项目根目录执行 `fes` 命令，输入`fes -h`则可以看到如下信息：
```
Usage: fes <command> [options]
一个好用的前端应用解决方案
Options:
-v, --vers output the current version
-h, --help display help for command
Commands:
build build application for production
dev [options] start a local http service for development
help show command helps
info print debugging information about your environment
webpack [options] inspect webpack configurations
Run fes <command> --help for detailed usage of given command.
```
### fes dev
启动本地开发服务器进行项目的开发调试。
```
Usage: fes dev [options]
start a local http service for development
Options:
--port http service port, like 8080
--https whether to turn on the https service
-h, --help display help for command
```
比如：
```bash
fes dev --port=8080
```
### fes build
编译构建 web 产物。
```
Usage: fes build [options]
build application for production
Options:
-h, --help display help for command
```
比如：
```
fes build
```
### fes help
打印帮助文档。
比如：
```bash
fes help
```
### fes info
打印当前项目的有用的环境信息，用来帮助定位问题。
```
Usage: fes info [options]
print debugging information about your environment
Options:
-h, --help display help for command
```
比如：
```bash
fes info
```
### fes webpack
查看项目使用的 webpack 配置。
```
Usage: fes webpack [options]
inspect webpack configurations
Options:
--rule <ruleName> inspect a specific module rule
--plugin <pluginName> inspect a specific plugin
--rules list all module rule names
--plugins list all plugin names
--verbose show full function definitions in output
-h, --help display help for command
```
比如：
```bash
fes webpack
```

56
docs/reference/components.md
View File

@ -1,56 +0,0 @@
# Built-in Components
## ClientOnly
- Usage:
```md
<ClientOnly>
<NonSsrFriendlyComponent />
</ClientOnly>
```
- Details:
This component and its children will only be rendered in client-side. That means, it will not be rendered to HTML during build (SSR).
If a component is trying to access Browser / DOM APIs directly in `setup()`, an error will occur during build because those APIs are unavailable in Node.js environment. In such case, you could do either:
- Modify the component to only access Browser / DOM APIs in `onBeforeMount()` or `onMounted()` hook.
- Wrap the component with `<ClientOnly>`.
## Content
- Props:
- pagePath
- Type: `string`
- Required: `false`
- Usage:
```md
<Content page-path="/" />
<Content page-path="/foo.html" />
```
- Details:
This component will render the Markdown content of a page.
If the `pagePath` prop is not provided, it will render the page of current route path.
This component is mainly for developing themes. You won't need it in most cases.
## OutboundLink
- Usage:
```md
<OutboundLink />
```
- Details:
This component will render an indicator for links to external URLs.
This component is mainly for developing themes. You won't need it in most cases.

574
docs/reference/config.md
View File

@ -1,574 +0,0 @@
# Config
Reference of VuePress config, which can be set via config file. The conventional config files are (in order of precedence):
- In current working directory `cwd`:
- `vuepress.config.ts`
- `vuepress.config.js`
- In source directory `sourceDir`:
- `.vuepress/config.ts`
- `.vuepress/config.js`
You can also specify the config file via `--config` option of [CLI](./cli.md).
## Site Config
### base
- Type: `string`
- Default: `/`
- Details:
The base URL the site will be deployed at.
You will need to set this if you plan to deploy your site under a sub path. It should always start and end with a slash. For example, if you plan to deploy your site to GitHub pages at `https://foo.github.io/bar/`, then you should set `base` to `"/bar/"`.
The `base` is automatically prepended to all the URLs that start with `/` in other options, so you only need to specify it once.
- Also see:
- [Guide > Assets > Base Helper](../guide/assets.md#base-helper)
- [Guide > Deployment](../guide/deployment.md)
### lang
- Type: `string`
- Default: `en-US`
- Details:
Language for the site.
This will be the `lang` attribute of the `<html>` tag in the rendered HTML.
This can be specified in different locales.
- Also see:
- [Config > locales](#locales)
- [Frontmatter > lang](./frontmatter.md#lang)
### title
- Type: `string`
- Default: `''`
- Details:
Title for the site.
This will be the suffix for all page titles, and displayed in the navbar in the default theme.
This can be specified in different locales.
- Also see:
- [Config > locales](#locales)
### description
- Type: `string`
- Default: `''`
- Details:
Description for the site.
This will be the `content` attribute of `<meta name="description" />` tag in the rendered HTML, which will be overrode by the `description` field of page frontmatter.
This can be specified in different locales.
- Also see:
- [Config > locales](#locales)
- [Frontmatter > description](./frontmatter.md#description)
### head
- Type: `HeadConfig[]`
- Default: `[]`
- Details:
Extra tags to inject into the `<head>` tag in the rendered HTML.
You can specify each tag in the form of `[tagName, { attrName: attrValue }, innerHTML?]`.
This can be specified in different locales.
- Example:
To add a custom favicon:
```js
module.exports = {
head: [
['link', { rel: 'icon', href: '/logo.png' }]
]
}
```
Rendered as：
```html
<head>
<link rel="icon" href="/logo.png" />
</head>
```
- Also see:
- [Config > locales](#locales)
- [Frontmatter > head](./frontmatter.md#head)
### locales
- Type: `{ [path: string]: Partial<SiteLocaleData> }`
- Default: `{}`
- Details:
Specify locales for i18n support.
Acceptable fields:
- [lang](#lang)
- [title](#title)
- [description](#description)
- [head](#head)
- Also see:
- [Guide > I18n](../guide/i18n.md)
## Theme Config
### theme
- Type: `string`
- Default: `'@vuepress/default'`
- Details:
Name or absolute path of theme your want to use.
This option accepts theme name, theme name shorthand, or absolute path to theme.
- Example:
```js
module.exports = {
theme: 'vuepress-theme-foo',
theme: 'bar',
theme: '/path/to/local/theme',
}
```
- Also see:
- [Guide > Theme](../guide/theme.md)
### themeConfig
- Type: `ThemeConfig`
- Default: `{}`
- Details:
Provide config options to the used theme. The options will vary depending on the theme you are using.
- Also see:
- [Default Theme > Config](./default-theme/config.md)
## Bundler Config
### bundler
- Type: `string`
- Default: `'@vuepress/webpack'`
- Details:
Name of bundler your want to use.
Bundler name shorthand is acceptable.
- Also see:
- [Guide > Bundler](../guide/bundler.md)
### bundlerConfig
- Type: `BundlerConfig`
- Default: `{}`
- Details:
Provide config options to the used bundler. The options will vary depending on the bundler you are using.
## Directory Config
### dest
- Type: `string`
- Default: `` `${sourceDir}/.vuepress/dist` ``
- Details:
Specify the output directory for `vuepress build` command.
### temp
- Type: `string`
- Default: `` `${sourceDir}/.vuepress/.temp` ``
- Details:
Specify the directory for temporary files.
### cache
- Type: `string`
- Default: `` `${sourceDir}/.vuepress/.cache` ``
- Details:
Specify the directory for cache .
### public
- Type: `string`
- Default: `` `${sourceDir}/.vuepress/public` ``
- Details:
Specify the directory for public files.
- Also see:
- [Guide > Assets > Public Files](../guide/assets.md#public-files)
## Markdown Config
### markdown
- Type: `MarkdownOptions`
- Default: `{}`
- Details:
Configure VuePress built-in Markdown syntax extensions.
- Also see:
- [Guide > Markdown > Syntax Extensions](../guide/markdown.md#syntax-extensions)
#### markdown.anchor
- Type: `AnchorPluginOptions | false`
- Details:
Options for [markdown-it-anchor](https://github.com/valeriangalliat/markdown-it-anchor).
Set to `false` to disable this plugin.
- Also see:
- [Guide > Markdown > Syntax Extensions > Header Anchors](../guide/markdown.md#header-anchors)
#### markdown.assets
- Type: `AssetsPluginOptions | false`
- Details:
Options for VuePress built-in markdown-it assets plugin.
Set to `false` to disable this plugin.
::: danger
You should not configure it unless you understand what it is for.
:::
#### markdown.code
- Type: `CodePluginOptions | false`
- Details:
Options for VuePress built-in markdown-it code plugin.
Set to `false` to disable this plugin.
- Also see:
- [Guide > Markdown > Syntax Extensions > Code Blocks](../guide/markdown.md#code-blocks)
##### markdown.code.highlight
- Type: `boolean`
- Default: `true`
- Details:
Enable code syntax highlighting or not.
You can disable it if you want to implement client side highlighting by yourself. For example, [Prismjs](https://prismjs.com/) or [highlight.js](https://highlightjs.org/).
- Also see:
- [Guide > Markdown > Syntax Extensions > Code Blocks > Syntax Highlighting](../guide/markdown.md#syntax-highlighting)
##### markdown.code.highlightLines
- Type: `boolean`
- Default: `true`
- Details:
Enable code line highlighting or not.
- Also see:
- [Guide > Markdown > Syntax Extensions > Code Blocks > Line Highlighting](../guide/markdown.md#line-highlighting)
##### markdown.code.lineNumbers
- Type: `boolean`
- Default: `true`
- Details:
Enable code line numbers or not.
- Also see:
- [Guide > Markdown > Syntax Extensions > Code Blocks > Line Numbers](../guide/markdown.md#line-numbers)
##### markdown.code.preWrapper
- Type: `boolean`
- Default: `true`
- Details:
Enable the extra wrapper of the `<pre>` tag or not.
The wrapper is required by the `highlightLines` and `lineNumbers`. That means, if you disable `preWrapper`, the line highlighting and line numbers will also be disabled.
You can disable it if you want to implement them in client side. For example, [Prismjs Line Highlight](https://prismjs.com/plugins/line-highlight/) or [Prismjs Line Numbers](https://prismjs.com/plugins/line-numbers/).
##### markdown.code.vPre
- Type: `boolean`
- Default: `true`
- Details:
Enable the `v-pre` directive on `<pre>` tag or not.
- Also see:
- [Guide > Markdown > Syntax Extensions > Code Blocks > Wrap with v-pre](../guide/markdown.md#wrap-with-v-pre)
#### markdown.customComponent
- Type: `undefined | false`
- Details:
Options for VuePress built-in markdown-it custom-component plugin.
Set to `false` to disable this plugin.
::: danger
You should not configure it unless you understand what it is for.
:::
#### markdown.emoji
- Type: `EmojiPluginOptions | false`
- Details:
Options for [markdown-it-emoji](https://github.com/markdown-it/markdown-it-emoji).
Set to `false` to disable this plugin.
- Also see:
- [Guide > Markdown > Syntax Extensions > Emoji](../guide/markdown.md#emoji)
#### markdown.extractHeaders
- Type: `ExtractHeadersPluginOptions | false`
- Details:
Options for VuePress built-in markdown-it extract-headers plugin.
It will extract page headers to page data, which will be used for generating sidebar, table of contents, etc. For example, the sidebar of current page is auto generated from the headers that extracted by this plugin.
Set to `false` to disable this plugin.
#### markdown.hoistTags
- Type: `HoistTagsPluginOptions | false`
- Details:
Options for VuePress built-in markdown-it hoist-tags plugin.
It will hoist specific HTML tags in your Markdown to the top-level of SFC. By default, only `<script>` and `<style>` tags will be hoisted. You can set this option to support SFC custom blocks in Markdown.
Set to `false` to disable this plugin.
- Also see:
- [Advanced > Markdown and Vue SFC](../guide/advanced/markdown.md)
#### markdown.links
- Type: `LinksPluginOptions | false`
- Details:
Options for VuePress built-in markdown-it links plugin.
It will convert internal links to `<RouterLink>`, and add extra attributes to external links.
Set to `false` to disable this plugin.
- Also see:
- [Guide > Markdown > Syntax Extensions > Links](../guide/markdown.md#links)
#### markdown.toc
- Type: `TocPluginOptions | false`
- Details:
Options for VuePress built-in markdown-it table-of-contents plugin.
Set to `false` to disable this plugin.
- Also see:
- [Guide > Markdown > Syntax Extensions > Table of Contents](../guide/markdown.md#table-of-contents)
## Development Config
### debug
- Type: `boolean`
- Default: `false`
- Details:
Enable debug mode or not.
This would be helpful for developers. Also, we are using [debug](https://github.com/visionmedia/debug) package for debug logging, which can be enabled via `DEBUG=vuepress*` environment variable.
### host
- Type: `string`
- Default: `'0.0.0.0'`
- Details:
Specify the host to use for the dev server.
### port
- Type: `number`
- Default: `8080`
- Details:
Specify the port to use for the dev server.
### open
- Type: `boolean`
- Default: `false`
- Details:
Whether to open the browser after dev-server had been started.
### evergreen
- Type: `boolean`
- Default: `true`
- Details:
Set to `true` if you are only targeting evergreen browsers. This will disable some transpilation and polyfills, and result in faster builds and smaller files.
### pagePatterns
- Type: `string[]`
- Default: `['**/*.md', '!.vuepress', '!node_modules']`
- Details:
Specify the patterns of files you want to be resolved as pages. The patterns are relative to the source directory.
### templateDev
- Type: `string`
- Default: `'@vuepress/client/templates/index.dev.html'`
- Details:
Specify the HTML template to be used for dev.
### templateSSR
- Type: `string`
- Default: `'@vuepress/client/templates/index.ssr.html'`
- Details:
Specify the HTML template to be used for build (SSR).
### shouldPreload
- Type: `((file: string, type: string) => boolean)) | boolean`
- Default: `true`
- Details:
A function to control what files should have `<link rel="preload">` resource hints generated. Set to `true` or `false` to enable or disable totally.
By default, only those files that are required by current page will be preloaded. So you can keep it `true` in most cases.
### shouldPrefetch
- Type: `((file: string, type: string) => boolean)) | boolean`
- Default: `false`
- Details:
A function to control what files should have `<link rel="prefetch">` resource hints generated. Set to `true` or `false` to enable or disable for all files.
If you set it to `true`, all files that required by other pages will be prefetched. This is good for small sites, which will speed up the navigation, but it might not be a good idea if you have lots of pages in your site.
## Plugin API
User config file also works as a VuePress plugin, so all of the Plugin APIs are available except the `name` and `multiple` options.
Please check out [Plugin API Reference](./plugin-api.md) for a full list of Plugin APIs.

339
docs/reference/config/README.md Normal file
View File

@ -0,0 +1,339 @@
---
sidebar: auto
---
# 配置
以下配置项通过字母排序。
## alias
- 类型： `object`
- 默认值： `{}`
- 详情：
配置别名，对引用路径进行映射。
- 示例：
```js
export default {
alias: {
main: 'src/assets/styles/main'
}
}
```
然后 `import('main')`，实际上是 `import('src/assets/styles/main')`。
## base
- 类型： `string`
- 默认值： `''`
- 详情：
设置路由前缀，通常用于部署到非根目录。比如你有路由 `/pageA`、`/pageB`，然后设置了 `base` 为 `/manage/`，那么就可以通过 `/manage/pageA`、`/manage/pageB` 访问到它们。
## chainWebpack
- 类型：`function`
- 默认值：`null`
- 详情：
通过 [webpack-chain](https://github.com/neutrinojs/webpack-chain) 的 API 修改 webpack 配置。
示例：
```js
export default {
chainWebpack(memo, { env, webpack }) {
// 删除 fes 内置插件
memo.plugins.delete('copy');
},
}
```
## cssLoader
- 类型： `object`
- 默认值： `''`
- 详情：
设置 [css-loader 配置项](https://github.com/webpack-contrib/css-loader#options)。
## copy
- 类型： `Array(string) || Array(object)`
- 默认值： `[]`
- 详情：
设置要复制到输出目录的文件、文件夹。
配置约定 `from-to` 规则， 其中 `from` 是相对于 `cwd` 的路径，`to` 是相对于输出路径的路径。
- 示例：
```js
export default {
copy: {
from: '/src/assets/images',
to: 'assets/images'
}
}
```
上面示例中，实现了将 `cwd` 路径中的 `/src/assets/images` 文件夹，在编译完成后，`copy` 到输出路径下的 `assets/images` 文件夹。
## define
- 类型： `object`
- 默认值： `{}`
- 详情：
用于提供给代码中可用的变量。
- 示例：
```js
export default {
define: {
__DEV__: 'development'
}
}
```
然后你代码里写 `console.log(__DEV__)`，会被编译成 `console.log('development')`。
## devServer
- 类型： `object`
- 默认值： `{}`
- 详情：
配置开发服务器。支持以下子配置项：
- port，端口号，默认 `8000`
- host，默认 `localhost`
- https，是否启用 https server，同时也会开启 HTTP/2
启用 port 和 host 也可以通过环境变量 `PORT` 和 `HOST` 临时指定。
## devtool
- 类型： `string`
- 默认值： `cheap-module-source-map` in dev, `undefined` in build
- 详情：
用户配置 sourcemap 类型。详见 [ webpack#devtool 配置](https://webpack.js.org/configuration/devtool/#devtool)。
## dynamicImport
- 类型： `boolean`
- 默认值： false
- 详情：
路由是否按需加载
## externals
- 类型：`object`
- 默认值：`{}`
- 详情：
设置哪些模块可以不被打包，通过 `<script>` 或其他方式引入。
示例：
```js
export default {
externals: {
vue: 'window.Vue',
},
}
```
## extraPostCSSPlugins
- 类型： `array`
- 默认值： `[]`
- 详情：
设置额外的 [postcss 插件](https://github.com/postcss/postcss/blob/master/docs/plugins.md)。
## inlineLimit
- 类型： `number`
- 默认值： `8192`(8k)
- 详情：
配置图片文件是否走 base64 编译的阈值。默认是 `8192` 字节，小于它会被编译为 base64 编码，否则会生成单独的文件。
## lessLoader
- 类型： `object`
- 默认值： `{}`
- 详情：
设置 [less-loader 配置项](https://github.com/webpack-contrib/less-loader)。
## mock
- 类型： `object || boolean`
- 默认值： `{}`
- 详情：
配置 mock 属性。
- 当 mock 为 `boolean` 类型时，`true` 表示打开 mock，`false` 表示关闭 mock。
- 当 mock 为 `object` 类型时，默认打开 mock。也可以通过子属性 `prefix` 添加过滤条件，满足条件的走 mock 文件。
- 示例：
```js
export default {
mock: {
prefix: '/api/auth'
}
}
```
然后所有以 `/api/users` 开始的请求，就能进入 mock.js 文件处理。
## mountElementId
- 类型： `string`
- 默认值： `app`
- 详情：
指定渲染到的 HTML 元素 id。
## nodeModulesTransform
- 类型： `object`
- 默认值： `{ exclude: [] }`
- 详情：
默认编译所有 `node_modules` 下的包，可以通过配置 `exclude` 来跳过某些包，以提高编译速度。
## outputPath
- 类型： `string`
- 默认值： `dist`
- 详情：
指定输出路径。
::: tip
不允许设定为 `src`、`public`、`pages` 等约定目录。
:::
## plugins
- 类型： `Array(string)`
- 默认值： `[]`
- 详情：
配置额外的 `fes` 插件。
数组项为指向插件的路径，可以是 npm 依赖、相对路径或绝对路径。如果是相对路径，则会从项目根目录开始找。
- 示例：
```js
export default {
plugins: [
// npm 依赖
'fes-plugin-hello',
// 相对路径
'./plugin',
// 绝对路径
`${__dirname}/plugin.js`,
],
};
```
## postcssLoader
- 类型： `object`
- 默认值： `{}`
- 详情：
设置 [postcss-loader 配置项](https://github.com/postcss/postcss-loader#options)。
## proxy
- 类型： `object`
- 默认值： `{}`
- 详情：
配置代理能力。
- 示例：
```js
export default {
proxy: {
'/v2': {
'target': 'https://api.douban.com/',
'changeOrigin': true,
}
}
}
```
然后访问 `/v2/movie/in_theaters_proxy` 就能访问到 [http://api.douban.com/v2/movie/in_theaters_proxy](http://api.douban.com/v2/movie/in_theaters_proxy) 的数据。
## publicpath
- 类型： `publicPath`
- 默认值： `/`
- 详情：
配置 webpack 的 publicPath。当打包的时候，webpack 会在静态文件路径前面添加 `publicPath` 的值，当你需要修改静态文件地址时，比如使用 CDN 部署，把 `publicPath` 的值设为 CDN 的值就可以。
## singular
- 类型： `boolean`
- 默认值： `false`
- 详情：
配置是否启用单数模式的目录。 比如 `src/pages` 的约定在开启后为 `src/page` 目录，@fesjs/fes-plugins 插件也遵照此配置的约定。
## targets
- 类型： `object`
- 默认值： `{}`
- 详情：
配置需要兼容的浏览器最低版本，会自动引入 polyfill 和做语法转换。
## terserOptions
- 类型： `object`
- 默认值：
```js
const defaultTerserOptions = {
compress: {
// turn off flags with small gains to speed up minification
arrows: false,
collapse_vars: false, // 0.3kb
comparisons: false,
computed_props: false,
hoist_funs: false,
hoist_props: false,
hoist_vars: false,
inline: false,
loops: false,
negate_iife: false,
properties: false,
reduce_funcs: false,
reduce_vars: false,
switches: false,
toplevel: false,
typeofs: false,
// a few flags with noticeable gains/speed ratio
// numbers based on out of the box vendor bundle
booleans: true, // 0.7kb
if_return: true, // 0.4kb
sequences: true, // 0.7kb
unused: true, // 2.3kb
// required features to drop conditional branches
conditionals: true,
dead_code: true,
evaluate: true
},
mangle: {
safari10: true
}
}
```
- 详情：
配置 [压缩器 terser 的配置项](https://github.com/terser/terser#minify-options)

106
docs/reference/default-theme/components.md
View File

@ -1,106 +0,0 @@
# Built-in Components
## Badge <Badge text="badge" />
- Props:
- type
- Type: `'tip' | 'warning' | 'danger'`
- Default: `'tip'`
- text
- Type: `string`
- Default: `''`
- vertical
- Type: `'top' | 'middle' | 'bottom' | undefined`
- Default: `undefined`
- Example:
**Input**
```md
- VuePress - <Badge type="tip" text="v2" vertical="top" />
- VuePress - <Badge type="warning" text="v2" vertical="middle" />
- VuePress - <Badge type="danger" text="v2" vertical="bottom" />
```
**Output**
- VuePress - <Badge type="tip" text="v2" vertical="top" />
- VuePress - <Badge type="warning" text="v2" vertical="middle" />
- VuePress - <Badge type="danger" text="v2" vertical="bottom" />
## CodeGroup
- Details:
Wrapper of the [CodeGroupItem](#codegroupitem) components.
## CodeGroupItem
- Props:
- title
- Type: `string`
- Required: `true`
- active
- Type: `boolean`
- Default: `false`
- Details:
This component must be placed inside a [CodeGroup](#codegroup) component.
Use the `active` prop to set the initial active item, or the first item will be activated by default.
- Example:
**Input**
````md
<CodeGroup>
<CodeGroupItem title="YARN">
```bash:no-line-numbers
yarn
```
</CodeGroupItem>
<CodeGroupItem title="NPM" active>
```bash:no-line-numbers
npm install
```
</CodeGroupItem>
</CodeGroup>
````
**Output**
<CodeGroup>
<CodeGroupItem title="YARN">
```bash:no-line-numbers
yarn
```
</CodeGroupItem>
<CodeGroupItem title="NPM" active>
```bash:no-line-numbers
npm install
```
</CodeGroupItem>
</CodeGroup>
::: warning
You must add an empty line between the starting tag of `<CodeGroupItem>` and the code fence, otherwise the code fence will not be parsed correctly by Markdown.
All content must be valid Markdown first, and then a Vue SFC.
Learn more: [Advanced > Markdown and Vue SFC](../../guide/advanced/markdown.md)
Alternatively, you can use the [custom containers](./markdown.md#custom-containers).
:::

603
docs/reference/default-theme/config.md
View File

@ -1,603 +0,0 @@
# Config
Reference of default theme config, which can be set via [themeConfig](../config.md#themeconfig).
## Basic Config
### locales
- Type: `{ [path: string]: Partial<DefaultThemeLocaleData> }`
- Default: `{}`
- Details:
Specify locales for i18n support.
All the options inside the [Locale Config](#locale-config) section can be used in locales.
This options will only take effect in default theme, so don't confuse with `locales` in [Site Config](../config.md#locales).
- Also see:
- [Guide > I18n](../../guide/i18n.md)
## Locale Config
Config of this section can be used as normal config, and can also be used in the [locales](#locales) option.
### home
- Type: `string`
- Default: `/`
- Details:
Specify the path of the homepage.
This will be used for:
- the logo link of the navbar
- the _back to home_ link of the 404 page
### navbar
- Type: `false | (NavbarItem | NavbarGroup | string)[]`
- Default: `[]`
- Details:
Configuration of navbar.
Set to `false` to disable navbar.
To configure the navbar items, you can set it to a _navbar array_, each item of which could be a `NavbarItem` object, a `NavbarGroup` object, or a string:
- A `NavbarItem` object should have a `text` field and a `link` field.
- A `NavbarGroup` object should have a `text` field and a `children` field. The `children` field should be a _navbar array_, too.
- A string should be the path to the target page file. It will be converted to a `NavbarItem` object, using the page title as `text`, and the page route path as `link`.
- Example 1:
```js
module.exports = {
themeConfig: {
navbar: [
// NavbarItem
{
text: 'Foo',
link: '/foo/',
},
// NavbarGroup
{
text: 'Group',
children: ['/group/foo.md', '/group/bar.md'],
},
// string - page file path
'/bar/README.md',
],
},
}
```
- Example 2:
```js
module.exports = {
themeConfig: {
navbar: [
// nested group - max depth is 2
{
text: 'Group',
children: [
{
text: 'SubGroup',
children: ['/group/sub/foo.md', '/group/sub/bar.md'],
},
],
},
],
},
}
```
### logo
- Type: `string`
- Details:
Specify the url of logo image.
The logo image will be displayed at the left end of the navbar.
- Example:
```js
module.exports = {
themeConfig: {
// public file path
logo: '/hero.png',
// url
logo: 'https://vuejs.org/images/logo.png',
},
}
```
- Also see:
- [Guide > Assets > Public Files](../../guide/assets.md#public-files)
### repo
- Type: `string`
- Details:
Specify the repository url of your project.
This will be used as the link of the _repository link_, which will be displayed as the last item of the navbar.
```js
module.exports = {
themeConfig: {
// If you set it in the form of `organization/repository`
// we will take it as a GitHub repo
repo: 'vuejs/vuepress',
// Use url directly if you are not using GitHub
repo: 'https://gitlab.com/foo/bar',
},
}
```
### repoLabel
- Type: `string`
- Details:
Specify the repository label of your project.
This will be used as the text of the _repository link_, which will be displayed as the last item of the navbar.
If you don't set this option explicitly, it will be automatically inferred from the [repo](#repo) option.
### selectLanguageText
- Type: `string`
- Details:
Specify the text of the _select language menu_.
The _select language menu_ will appear next to the repository button in the navbar when you set multiple [locales](../config.md#locales) in your site config.
### selectLanguageAriaLabel
- Type: `string`
- Details:
Specify the `aria-label` attribute of the _select language menu_.
This is mainly for a11y purpose.
### selectLanguageName
- Type: `string`
- Details:
Specify the name of the language of a locale.
This option will **only take effect inside** the [locales](#locales) of your theme config. It will be used as the language name of the locale, which will be displayed in the _select language menu_.
- Example:
```js
module.exports = {
locales: {
'/': {
lang: 'en-US',
},
'/zh/': {
lang: 'zh-CN',
},
},
themeConfig: {
locales: {
'/': {
selectLanguageName: 'English',
},
'/zh/': {
selectLanguageName: '简体中文',
},
},
},
}
```
### sidebar
- Type: `false | 'auto' | SidebarConfigArray | SidebarConfigObject`
- Default: `'auto'`
- Details:
Configuration of sidebar.
You can override this global option via [sidebar](./frontmatter.md#sidebar) frontmatter in your pages.
Set to `false` to disable sidebar.
If you set it to `'auto'`, the sidebar will be automatically generated from the page headers.
To configure the sidebar items manually, you can set this option to a _sidebar array_, each item of which could be a `SidebarItem` object, a `SidebarGroup` object, or a string:
- A `SidebarItem` object should have a `text` field, a `link` field, and a `children` field. The `children` field should be an array of `SidebarItem` or string.
- A `SidebarGroup` object should set `isGroup` field to `true`, and should have a `text` field and a `children` field. The `children` field should be an array of `SidebarItem` or string.
- A string should be the path to the target page file. It will be converted to a `SidebarItem` object, whose `text` is the page title, `link` is the page route path, and `children` is automatically generated from the page headers.
If you want to set different sidebar for different sub paths, you can set this option to a _sidebar object_:
- The key should be the path prefix.
- The value should be a _sidebar array_.
- Example 1:
```js
module.exports = {
themeConfig: {
// sidebar array
// all pages will use the same sidebar
sidebar: [
// SidebarItem
{
text: 'Foo',
link: '/foo/',
children: [
// SidebarItem
{
text: 'github',
link: 'https://github.com',
children: [],
},
// string - page file path
'/foo/bar.md',
],
},
// SidebarGroup
{
isGroup: true,
text: 'Group',
children: ['/group/foo.md', '/group/bar.md'],
},
// string - page file path
'/bar/README.md',
],
},
}
```
- Example 2:
```js
module.exports = {
themeConfig: {
// sidebar object
// pages under different sub paths will use different sidebar
sidebar: {
'/guide/': [
{
isGroup: true,
text: 'Guide',
children: ['/guide/README.md', '/guide/getting-started.md'],
},
],
'/reference/': [
{
isGroup: true,
text: 'Reference',
children: ['/reference/cli.md', '/reference/config.md'],
},
],
},
},
}
```
### editLink
- Type: `boolean`
- Default: `true`
- Details:
Enable the _edit this page_ link or not.
You can override this global option via [editLink](./frontmatter.md#editlink) frontmatter in your pages.
### editLinkText
- Type: `string`
- Default: `'Edit this page'`
- Details:
Specify the text of the _edit this page_ link.
### editLinkPattern
- Type: `string`
- Details:
Specify the pattern of the _edit this page_ link.
This will be used for generating the _edit this page_ link.
If you don't set this option, the pattern will be inferred from the [docsRepo](#docsrepo) option. But if your documentation repository is not hosted on a common platform, for example, GitHub, GitLab, Bitbucket, etc., you have to set this option explicitly to make the _edit this page_ link work.
- Usage:
| Pattern | Description |
|-----------|-----------------------------------------------------------------------------------------------------|
| `:repo` | The docs repo url, i.e. [docsRepo](#docsrepo) |
| `:branch` | The docs repo branch, i.e. [docsBranch](#docsbranch) |
| `:path` | The path of the page source file, i.e. [docsDir](#docsdir) joins the relative path of the page file |
- Example:
```js
module.exports = {
themeConfig: {
docsRepo: 'https://gitlab.com/owner/name',
docsBranch: 'master',
docsDir: 'docs',
editLinkPattern: ':repo/-/edit/:branch/:path',
},
}
```
The generated link will look like `'https://gitlab.com/owner/name/-/edit/master/docs/path/to/file.md'`.
### docsRepo
- Type: `string`
- Details:
Specify the repository url of your documentation source files.
This will be used for generating the _edit this page_ link.
If you don't set this option, it will use the [repo](#repo) option by default. But if your documentation source files are in a different repository, you will need to set this option.
### docsBranch
- Type: `string`
- Default: `'main'`
- Details:
Specify the repository branch of your documentation source files.
This will be used for generating the _edit this page_ link.
### docsDir
- Type: `string`
- Default: `''`
- Details:
Specify the directory of your documentation source files in the repository.
This will be used for generating the _edit this page_ link.
### lastUpdated
- Type: `boolean`
- Default: `true`
- Details:
Enable the _last updated timestamp_ or not.
You can override this global option via [lastUpdated](./frontmatter.md#lastupdated) frontmatter in your pages.
Notice that if you set `themeConfig.lastUpdated` to `false`, this feature will be disabled totally and could not be enabled in locales nor page frontmatter.
### lastUpdatedText
- Type: `string`
- Default: `'Last Updated'`
- Details:
Specify the text of the _last updated timestamp_ label.
### contributors
- Type: `boolean`
- Default: `true`
- Details:
Enable the _contributors list_ or not.
You can override this global option via [contributors](./frontmatter.md#contributors) frontmatter in your pages.
Notice that if you set `themeConfig.contributors` to `false`, this feature will be disabled totally and could not be enabled in locales nor page frontmatter.
### contributorsText
- Type: `string`
- Default: `'Contributors'`
- Details:
Specify the text of the _contributors list_ label.
### tip
- Type: `string`
- Default: `'TIP'`
- Details:
Specify the default title of the tip [custom containers](./markdown.md#custom-containers).
### warning
- Type: `string`
- Default: `'WARNING'`
- Details:
Specify the default title of the warning [custom containers](./markdown.md#custom-containers).
### danger
- Type: `string`
- Default: `'WARNING'`
- Details:
Specify the default title of the danger [custom containers](./markdown.md#custom-containers).
### notFound
- Type: `string[]`
- Default: `['Not Found']`
- Details:
Specify the messages of the 404 page.
The message will be randomly picked from the array when user enter the 404 page.
### backToHome
- Type: `string`
- Default: `'Back to home'`
- Details:
Specify the text of the _back to home_ link in the 404 page.
### openInNewWindow
- Type: `string`
- Default: `'open in new window'`
- Details:
Specify the `sr-only` text of the [OutboundLink](../components.md#outboundlink).
This is mainly for a11y purpose.
## Plugins
### themePlugins
- Details:
Configure the plugins that used by default theme.
Default theme is using some plugins by default. You can disable a plugin if you really do not want to use it. Make sure you understand what the plugin is for before disabling it.
#### themePlugins.activeHeaderLinks
- Type: `boolean`
- Default: `true`
- Details:
Enable [@vuepress/plugin-active-header-links](../plugin/active-header-links.md) or not.
#### themePlugins.backToTop
- Type: `boolean`
- Default: `true`
- Details:
Enable [@vuepress/plugin-back-to-top](../plugin/back-to-top.md) or not.
#### themePlugins.container
- Type: `Record<ContainerType, boolean>`
- Details:
Enable custom containers that powered by [@vuepress/plugin-container](../plugin/container.md) or not.
`ContainerType` type is:
- `tip`
- `warning`
- `danger`
- `details`
- `codeGroup`
- `codeGroupItem`
- Also see:
- [Default Theme > Markdown > Custom Containers](./markdown.md#custom-containers)
#### themePlugins.debug
- Type: `boolean`
- Default: `true`
- Details:
Enable [@vuepress/plugin-debug](../plugin/debug.md) or not.
#### themePlugins.git
- Type: `boolean`
- Default: `true`
- Details:
Enable [@vuepress/plugin-git](../plugin/git.md) or not.
#### themePlugins.mediumZoom
- Type: `boolean`
- Default: `true`
- Details:
Enable [@vuepress/plugin-medium-zoom](../plugin/medium-zoom.md) or not.
#### themePlugins.nprogress
- Type: `boolean`
- Default: `true`
- Details:
Enable [@vuepress/plugin-nprogress](../plugin/nprogress.md) or not.

252
docs/reference/default-theme/frontmatter.md
View File

@ -1,252 +0,0 @@
# Frontmatter
## Home Page
Frontmatter in this section will only take effect in home pages.
### home
- Type: `boolean`
- Details:
Specify whether the page is homepage or a normal page.
If you don't set this frontmatter or set it to `false`, the page would be a [normal page](#normal-page).
- Example:
```md
---
home: true
---
```
### heroImage
- Type: `string`
- Details:
Specify the url of the hero image.
- Example:
```md
---
# public file path
heroImage: /hero.png
# url
heroImage: https://vuejs.org/images/logo.png
---
```
- Also see:
- [Guide > Assets > Public Files](../../guide/assets.md#public-files)
### heroAlt
- Type: `string`
- Details:
Specify the `alt` attribute of the hero image.
This will fallback to the [heroText](#heroText).
### heroText
- Type: `string | null`
- Details:
Specify the the hero text.
This will fallback to the site [title](../config.md#title).
Set to `null` to disable hero text.
### tagline
- Type: `string | null`
- Details:
Specify the the tagline.
This will fallback to the site [description](../config.md#description).
Set to `null` to disable tagline.
### actions
- Type:
```ts
Array<{
text: string
link: string
type?: 'primary' | 'secondary'
}>
```
- Details:
Configuration of the action buttons.
- Example:
```md
---
actions:
- text: Get Started
link: /guide/getting-started.html
type: primary
- text: Introduction
link: /guide/
type: secondary
---
```
### features
- Type:
```ts
Array<{
title: string
details: string
}>
```
- Details:
Configuration of the features list.
- Example:
```md
---
features:
- title: Simplicity First
details: Minimal setup with markdown-centered project structure helps you focus on writing.
- title: Vue-Powered
details: Enjoy the dev experience of Vue, use Vue components in markdown, and develop custom themes with Vue.
- title: Performant
details: VuePress generates pre-rendered static HTML for each page, and runs as an SPA once a page is loaded.
---
```
### footer
- Type: `string`
- Details:
Specify the content of the footer.
### footerHtml
- Type: `boolean`
- Details:
Allow HTML in footer or not.
If you set it to `true`, the [footer](#footer) will be treated as HTML code.
## Normal Page
Frontmatter in this section will only take effect in normal pages.
### editLink
- Type: `boolean`
- Details:
Enable the _edit this page_ link in this page or not.
- Also see:
- [Default Theme > Config > editLink](./config.md#editlink)
### lastUpdated
- Type: `boolean`
- Details:
Enable the _last updated timestamp_ in this page or not.
- Also see:
- [Default Theme > Config > lastUpdated](./config.md#lastupdated)
### contributors
- Type: `boolean`
- Details:
Enable the _contributors list_ in this page or not.
- Also see:
- [Default Theme > Config > contributors](./config.md#contributors)
### sidebar
- Type: `false | 'auto' | SidebarConfigArray | SidebarConfigObject`
- Details:
Configure the sidebar of this page.
- Also see:
- [Default Theme > Config > sidebar](./config.md#sidebar)
### prev
- Type: `NavLink | string`
- Details:
Specify the link of the previous page.
If you don't set this frontmatter, the link will be inferred from the sidebar config.
To configure the prev link manually, you can set this frontmatter to a `NavLink` object or a string:
- A `NavLink` object should have a `text` field and a `link` field.
- A string should be the path to the target page file. It will be converted to a `NavLink` object, whose `text` is the page title, and `link` is the page route path.
- Example:
```md
---
# NavLink
prev:
text: Get Started
link: /guide/getting-started.html
# NavLink - external url
prev:
text: GitHub
link: https://github.com
# string - page file path
prev: /guide/getting-started.md
# string - page file relative path
prev: ../../guide/getting-started.md
---
```
### next
- Type: `NavLink | string`
- Details:
Specify the link of the next page.
If you don't set this frontmatter, the link will be inferred from the sidebar config.
The type is the same as [prev](#prev) frontmatter.

124
docs/reference/default-theme/markdown.md
View File

@ -1,124 +0,0 @@
# Markdown
## Custom Containers
- Usage:
```md
::: <type> [title]
[content]
:::
```
The `type` is required, and the `title` and `content` are optional.
Supported `type` :
- `tip`
- `warning`
- `danger`
- `details`
- Alias of [CodeGroup](./components.md#codegroup) and [CodeGroupItem](./components.md#codegroupitem):
- `code-group`
- `code-group-item`
- Example 1 (default title):
**Input**
```md
::: tip
This is a tip
:::
::: warning
This is a warning
:::
::: danger
This is a dangerous warning
:::
::: details
This is a details block, which does not work in IE / Edge
:::
```
**Output**
::: tip
This is a tip
:::
::: warning
This is a warning
:::
::: danger
This is a dangerous warning
:::
::: details
This is a details block, which does not work in IE / Edge
:::
- Example 2 (custom title):
**Input**
````md
::: danger STOP
Danger zone, do not proceed
:::
::: details Click me to view the code
```js
console.log('Hello, VuePress!')
```
:::
````
**Output**
::: danger STOP
Danger zone, do not proceed
:::
::: details Click me to view the code
```js
console.log('Hello, VuePress!')
```
:::
- Example 3 (code group alias):
**Input**
````md
:::: code-group
::: code-group-item FOO
```js
const foo = 'foo'
```
:::
::: code-group-item BAR
```js
const bar = 'bar'
```
:::
::::
````
**Output**
:::: code-group
::: code-group-item FOO
```js
const foo = 'foo'
```
:::
::: code-group-item BAR
```js
const bar = 'bar'
```
:::
::::

165
docs/reference/frontmatter.md
View File

@ -1,165 +0,0 @@
# Frontmatter
## lang
- Type: `string`
- Details:
Language for the page.
This will override the `lang` option in your site config.
- Also see:
- [Config > lang](./config.md#lang)
## title
- Type: `string`
- Details:
Title for the page.
If you don't specify `title` in frontmatter, content of the first level-one header (i.e. `# title`) will be used as the title.
## description
- Type: `string`
- Details:
Description for the page.
This will override the `description` option in your site config.
- Also see:
- [Config > description](./config.md#description)
## head
- Type: `HeadConfig[]`
- Details:
Extra tags in `<head>` tag for the page.
- Example:
```md
---
head:
- - meta
- name: foo
content: bar
- - link
- rel: canonical
href: foobar
---
```
Rendered as:
```html
<head>
<meta name="foo" content="bar" />
<link rel="canonical" href="foobar" />
</head>
```
- Also see:
- [Config > head](./config.md#head)
## date
- Type: `string`
- Details:
Created date for the page.
You should specify the date in the form of `yyyy-MM-dd`, or follow the [YAML Timestamp Type](https://yaml.org/type/timestamp.html).
## permalink
- Type: `string`
- Details:
Permalink for the page.
This will override the default route path that determined by the file path of the page.
- Also see:
- [Frontmatter > permalinkPattern](#permalinkpattern)
- [Guide > Page > Routing](../guide/page.md#routing)
## permalinkPattern
- Type: `string`
- Details:
Pattern to generate permalink for the page.
This won't take effect if the `permalink` frontmatter has been set.
- Usage:
| Pattern | Description |
|-----------|-----------------------------|
| `:year` | Year part of created date |
| `:month` | Month part of created date |
| `:day` | Day part of created date |
| `:slug` | Slug of page filename |
| `:raw` | Raw route path |
The `:year`, `:month` and `:day` patterns are resolved according to the following priority:
- The `date` frontmatter.
- The filename that matches the date pattern `yyyy-MM-dd-foobar.md` or `yyyy-MM-foobar.md`.
- The dirname that matches the date pattern `yyyy/MM/dd/foobar.md` or `yyyy/MM/foobar.md`.
- Fallback to `1970-01-01`.
- Example:
- Case 1:
The page filename is `foo-bar.md`.
The page frontmatter is:
```md
---
date: 2021-01-03
permalinkPattern: :year/:month/:day/:slug.html
---
```
Then the permalink of the page would be `2021/01/03/foo-bar.html`.
- Case 2:
The page filename is `2021-01-03-bar-baz.md`.
The page frontmatter is:
```md
---
permalinkPattern: :year/:month/:day/:slug.html
---
```
Then the permalink of the page would be `2021/01/03/bar-baz.html`.
- Also see:
- [Frontmatter > date](#date)
- [Frontmatter > permalink](#permalink)
## layout
- Type: `string`
- Details:
Layout for the page.

285
docs/reference/plugin-api.md
View File

@ -1,285 +0,0 @@
# Plugin API
Plugins should be used before initialization. The basic options will be handled once the plugin is used:
- [name](#name)
- [multiple](#multiple)
- [plugins](#plugins)
The following hooks will be processed when initializing app:
- [extendsMarkdown](#extendsmarkdown)
- [onInitialized](#oninitialized)
The following hooks will be processed when preparing files:
- [extendsPageData](#extendspagedata)
- [clientAppEnhanceFiles](#clientappenhancefiles)
- [clientAppRootComponentFiles](#clientapprootcomponentfiles)
- [clientAppSetupFiles](#clientappsetupfiles)
- [onPrepared](#onprepared)
The following hooks will be processed in dev / build:
- [alias](#alias)
- [define](#define)
- [onGenerated](#ongenerated)
## Basic Options
### name
- Type: `string`
- Details:
Name of the plugin.
It will be used for identifying plugins to avoid using a same plugin multiple times, so make sure to use a unique plugin name.
It is recommended to use following format:
- Non-scoped: `vuepress-plugin-foo`
- Scoped: `@org/vuepress-plugin-foo`
- Also see:
- [Plugin API > multiple](#multiple)
### multiple
- Type: `boolean`
- Default: `false`
- Details:
Declare whether the plugin can be used multiple times.
If set to `false`, when using plugins with the same name, the one used previously will be replaced by the one used later.
If set to `true`, plugins with the same name could be used multiple times and won't be replaced.
- Also see:
- [Plugin API > name](#name)
### plugins
- Type: `PluginConfig[]`
- Details:
Plugins to use.
A plugin can use other plugins via this option.
This option accepts an array, each item of which is a two-element tuple:
- The first element is the plugin name or the plugin itself. It accepts plugin name, plugin name shorthand, absolute path to plugin, or the plugin object.
- The second element is the plugin options. It accepts boolean or object. Set it to `false` to disable the plugin. Set it to `true` to enable the plugin without any options. Use object to enable the plugin with options.
For simplicity, you can use the first element of the tuple that described above as the array item, which equals enabling the plugin without any options.
- Example:
```js
module.exports = {
plugins: [
// two-element tuple
['vuepress-plugin-foo', false],
['bar', true],
['/path/to/local/plugin', { /* options */ }],
[require('vuepress-plugin-baz'), true],
// only use the first element
'foobar', // equals to ['foobar', true]
],
}
```
- Also see:
- [Guide > Plugin](../guide/plugin.md)
## Development Hooks
### alias
- Type: `Record<string, any> | ((app: App) => Record<string, any>)`
- Details:
Path aliases definition.
This hook accepts an object or a function that returns an object.
- Example:
```js
module.exports = {
alias: {
'@alias': '/path/to/alias',
},
}
```
### define
- Type: `Record<string, any> | ((app: App) => Record<string, any>)`
- Details:
Define global constants replacements.
This hook accepts an object or a function that returns an object.
This can be useful for passing variables to client files. Note that the values will be automatically processed by `JSON.stringify()`.
- Example:
```js
module.exports = {
define: {
__GLOBAL_BOOLEAN__: true,
__GLOBAL_STRING__: 'foobar',
__GLOBAL_OBJECT__: { foo: 'bar' },
},
}
```
### extendsMarkdown
- Type: `(md: Markdown, app: App) => void`
- Details:
Markdown enhancement.
This hook accepts a function that will receive an instance of `Markdown` powered by [markdown-it](https://github.com/markdown-it/markdown-it) in its arguments.
This can be used for using extra markdown-it plugins and implementing customizations.
- Example:
```js
module.exports = {
extendsMarkdown: (md) => {
md.use(plugin1)
md.linkify.set({ fuzzyEmail: false })
},
}
```
### extendsPageData
- Type: `(page: Page, app: App) => Record<string, any> | Promise<Record<string, any>>`
- Details:
Page data extension.
This hook accepts a function that will receive an instance of `Page`. The returned object will be merged into page data, which can be used in client side code.
- Example:
```js
module.exports = {
extendsPageData: (page) => {
const meta = 'foobar'
return { meta }
},
}
```
In client component:
```js
import { usePageData } from '@vuepress/client'
export default {
setup() {
const page = usePageData()
console.log(page.value.meta) // foobar
},
}
```
## Client Files Hooks
### clientAppEnhanceFiles
- Type: `string | string[] | ((app: App) => string | string[] | Promise<string | string[]>)`
- Details:
Paths of client app enhancement files.
This hook accepts absolute file paths, or a function that returns the paths.
- Example:
```js
module.exports = {
clientAppEnhanceFiles: '/path/to/clientAppEnhance.js',
}
```
### clientAppRootComponentFiles
- Type: `string | string[] | ((app: App) => string | string[] | Promise<string | string[]>)`
- Details:
Paths of client app root component files.
This hook accepts absolute file paths, or a function that returns the paths.
- Example:
```js
module.exports = {
clientAppRootComponentFiles: '/path/to/RootComponent.vue',
}
```
### clientAppSetupFiles
- Type: `string | string[] | ((app: App) => string | string[] | Promise<string | string[]>)`
- Details:
Paths of client app setup files.
This hook accepts absolute file paths, or a function that returns the paths.
- Example:
```js
module.exports = {
clientAppSetupFiles: '/path/to/clientAppSetup.js',
}
```
## Lifecycle Hooks
### onInitialized
- Type: `(app: App) => void | Promise<void>`
- Details:
This hook will be invoked once VuePress app has been initialized.
### onPrepared
- Type: `(app: App) => void | Promise<void>`
- Details:
This hook will be invoked once VuePress app has finished preparation.
### onGenerated
- Type: `(app: App) => void | Promise<void>`
- Details:
This hook will be invoked once VuePress app has generated static files.

12
docs/reference/plugin/README.md
View File

@ -1,3 +1,11 @@
# Official Plugins
## 架构
> TODO
![架构](/framework.png "架构")
Fes.js 把大家常用的技术栈封装成一个个插件进行整理，收敛到一起，让大家只用 Fes.js 就可以完成 80% 的日常工作。
## 插件和插件集
<p>
<img src="/plugins.png" alt="插件" title="插件" style="width: 500px" class="medium-zoom-image">
</p>
Fes.js 支持插件和插件集，通过这张图应该很好理解到他们的关系，通过插件集我们把插件收敛依赖然后支持不同的业务类型。

3
docs/reference/plugin/active-header-links.md
View File

@ -1,3 +0,0 @@
# active-header-links
> TODO

1
docs/reference/plugin/api.md Normal file
View File

@ -0,0 +1 @@
# 插件API

3
docs/reference/plugin/back-to-top.md
View File

@ -1,3 +0,0 @@
# back-to-top
> TODO

3
docs/reference/plugin/container.md
View File

@ -1,3 +0,0 @@
# container
> TODO

3
docs/reference/plugin/debug.md
View File

@ -1,3 +0,0 @@
# debug
> TODO

3
docs/reference/plugin/docsearch.md
View File

@ -1,3 +0,0 @@
# docsearch
> TODO

3
docs/reference/plugin/git.md
View File

@ -1,3 +0,0 @@
# git
> TODO

3
docs/reference/plugin/google-analytics.md
View File

@ -1,3 +0,0 @@
# google-analytics
> TODO

3
docs/reference/plugin/medium-zoom.md
View File

@ -1,3 +0,0 @@
# medium-zoom
> TODO

3
docs/reference/plugin/nprogress.md
View File

@ -1,3 +0,0 @@
# nprogress
> TODO

3
docs/reference/plugin/palette-stylus.md
View File

@ -1,3 +0,0 @@
# palette-stylus
> TODO

254
docs/reference/plugin/plugins/access.md Normal file
View File

@ -0,0 +1,254 @@
# @fesjs/plugin-access
## 介绍
对于前端应用来说，权限就是页面、页面元素是否可见。
### 资源
Fes.js 把页面、页面元素统一叫做资源，每个资源都有 `accessId`：
- 页面的 `accessId` 默认是页面的路由 `path` 。比如页面 `pages/a.vue` 的路由 `path` 是 `/a`。当页面访问 `/a` 时会渲染当前页面，`/a` 也就是页面的 `accessId`。
- 页面元素的 `accessId` 没有默认值，我们可以自定义。
```vue
<template>
<access :id="accessId"> accessOnepicess1 <input /> </access>
<div v-access="accessId"> accessOnepicess2 </div>
</template>
<script>
export default {
setup(){
return {
accessId: 'accessOnepicess'
}
}
}
</script>
```
### 角色
Fes.js 用角色定义一组资源。当访问 Fes.js 应用时，使用插件提供的 API 设置用户的角色，角色对应的资源才可见，非角色对应的资源不可见。
当然有时候业务比较复杂，角色不能在前端应用中预先定义，而是用户自定义的，储存在数据库中。不要怕！插件也提供粒度更细的 API 来控制当前用户能访问的资源。
## 启用方式
在 `package.json` 中引入依赖：
```json
{
"dependencies": {
"@fesjs/fes": "^2.0.0",
"@fesjs/plugin-access": "^2.0.0"
},
}
```
## 配置
### 编译时配置
在执行 `fes dev` 或者 `fes build` 时，通过此配置生成运行时的代码，在配置文件`.fes.js` 中配置：
```js
export default {
access: {
roles: {
admin: ["/", "/onepiece", '/store']
}
}
}
```
#### roles
- **类型**：对象
- **默认值**：`{}`
- **详情**：
角色预定义列表。`key` 是角色 Id ，`value`是角色 Id 对应的资源列表。
### 运行时配置
在 `app.js` 中配置
#### unAccessHandler
- **类型**：`Function`
- **默认值**：`null`
- **详情**：
当进入某个路由时，如果路由对应的页面不属于可见资源列表，则会暂停进入，调用 `unAccessHandler` 函数。
- **参数**
- router：createRouter 创建的路由实例
- to： 准备进入的路由
- from：离开的路由
- next： [next函数](https://next.router.vuejs.org/zh/guide/advanced/navigation-guards.html#%E5%8F%AF%E9%80%89%E7%9A%84%E7%AC%AC%E4%B8%89%E4%B8%AA%E5%8F%82%E6%95%B0-next)
比如：
```js
export const access = {
unAccessHandler({ to, next }) {
const accesssIds = accessApi.getAccess();
if (to.path === '/404') {
accessApi.setAccess(accesssIds.concat(['/404']));
return next('/404');
}
if (!accesssIds.includes('/403')) {
accessApi.setAccess(accesssIds.concat(['/403']));
}
next('/403');
}
};
```
#### noFoundHandler
- **类型**：`Function`
- **默认值**：`null`
- **详情**：
当进入某个路由时，如果路由对应的页面不存在，则会调用 `noFoundHandler` 函数。
- **参数**
- router：createRouter 创建的路由实例
- to： 准备进入的路由
- from：离开的路由
- next： [next函数](https://next.router.vuejs.org/zh/guide/advanced/navigation-guards.html#%E5%8F%AF%E9%80%89%E7%9A%84%E7%AC%AC%E4%B8%89%E4%B8%AA%E5%8F%82%E6%95%B0-next)
比如：
```js
export const access = {
noFoundHandler({ next }) {
const accesssIds = accessApi.getAccess();
if (!accesssIds.includes('/404')) {
accessApi.setAccess(accesssIds.concat(['/404']));
}
next('/404');
}
};
```
## API
### access
插件 API 通过 `@fesjs/fes` 导出：
```js
import { access } from '@fesjs/fes'
```
#### access.hasAccess
- **类型**：函数
- **详情**: 判断某个资源是否可见。
- **参数**：
- accessId，资源Id
- **返回值**：Boolean
#### access.isDataReady
- **类型**：函数
- **详情**：可以用异步数据来设置权限，`isDataReady` 用来判断异步数据是否已经加载完毕。
- **参数**：null
- **返回值**：Boolean
```js
import { access } from '@fesjs/fes';
console.log(access.isDataReady())
```
#### access.setRole
- **类型**：函数
- **详情**：设置当前的角色。
- **参数**：
- roleId，角色Id，有两种类型：
- String，对应着 `roles` 配置对象中的 `key`。
- Promise，Promise resolve 的结果应对应着 `roles` 配置对象中的 `key`。
```js
import { access } from '@fesjs/fes';
access.setRole(['admin'])
```
#### access.setAccess
- **类型**：函数
- **详情**：设置当前的角色。
- **参数**：
- accessIds，资源Id数组，有两种类型：
- Array，数组项对应着 `roles` 配置对象中的 `key`。
- Promise，Promise resolve 的结果应该是`Array<accessId>`。
```js
import { access } from '@fesjs/fes';
access.setAccess(['/a', '/b', '/c'])
```
#### access.getAccess
- **类型**：函数
- **详情**：返回当前可见的资源列表。
- **参数**：null
```js
import { access } from '@fesjs/fes';
access.getAccess();
```
### useAccess
- **类型**：[composition]((https://v3.cn.vuejs.org/guide/composition-api-introduction.html)) 函数
- **详情**：判断某个资源是否可见。
- **参数**：
- accessId，资源Id
- **返回值**：`ref`
```vue
<template>
<div v-if="accessOnepicess">accessOnepicess</div>
</template>
<script>
import { useAccess } from '@fesjs/fes';
export default {
setup(){
const accessOnepicess = useAccess('/onepiece1');
return {
accessOnepicess
}
}
}
</script>
```
### v-access
在指令 `v-access` 中传入 `accessId`，则当 `accessId` 拥有权限时渲染DOM，当没有权限时隐藏此DOM。
```vue
<template>
<div v-access="accessId"> accessOnepicess2 </div>
</template>
<script>
export default {
setup(){
return {
accessId: 'accessOnepicess'
}
}
}
</script>
```
### 组件 Access
组件 `Access` 中传入 `accessId`，则当 `accessId` 拥有权限时渲染此组件，当没有权限时隐藏此组件。
```vue
<template>
<access :id="accessId"> accessOnepicess1 <input /> </access>
</template>
<script>
export default {
setup(){
return {
accessId: 'accessOnepicess'
}
}
}
</script>
```

226
docs/reference/plugin/plugins/enums.md Normal file
View File

@ -0,0 +1,226 @@
# @fesjs/plugin-enums
## 介绍
日常业务开发中，有很多场景会使用到枚举值，比如select-options、table-column。
该插件提供统一的枚举存取及丰富的函数来处理枚举。
## 启用方式
在 `package.json` 中引入依赖：
```json
{
"dependencies": {
"@fesjs/fes": "^2.0.0",
"@fesjs/plugin-enums": "^2.0.0"
}
}
```
## 配置
### 静态配置
在 `.fes.js` 中配置：
```js
// 配置格式：[[key, value], ...]
export default {
enums: {
status: [['0', '无效的'], ['1', '有效的']]
}
}
```
### 动态配置
在业务代码中
```js
import { enums } from '@fesjs/fes';
// 动态添加
enums.push('status', [['0', '无效的'], ['1', '有效的']]
enums.get('status', '1') // 有效的
```
## 场景使用
- 动态添加的枚举项支持数组和对象
- 枚举项为对象时，可以指定keyName和valueName属性名
- 导出枚举值，可指定取值的路径
- 导出枚举可扩展属性
```vue
<template>
<div>
<!-- 遍历枚举status -->
<div v-for="item in enumsGet('status')" :key="item.key">
{{item.value}}：{{item.key}}
</div>
<!-- 遍历枚举扩展后的roles -->
<div v-for="item in roles" :key="item.key">
{{item.name}}：{{item.disabled}}
</div>
<!-- 获取枚举roles为2的英文名 -->
<div>{{enumsGet('roles', '2', { dir: 'eName' })}}</div>
</div>
</template>
<script>
import { enums } from '@fesjs/fes';
export default {
setup() {
// 动态添加枚举，枚举项是对象，并指定key的属性名为id
enums.push('roles', [
{
id: '1',
cName: '系统管理员',
eName: 'System',
perm: ['1', '2', '3']
},
{
id: '2',
cName: '业务管理员',
eName: 'Business',
perm: ['1', '2']
},
{
id: '3',
cName: '普通用户',
eName: 'User',
perm: ['1']
}
], { keyName: 'id' });
// 导出定制格式的roles，扩展枚举项新的属性name、disabled
const roles = enums.get('roles', {
extend: [
{
key: 'name',
dir: 'cName' // 指定取值路径，取属性cName的值
},
{
key: 'disabled',
// 传入函数，获取结果值
transfer: item => item.value.perm.some(i => i >= 2)
}
]
});
console.log(roles);
// [{key: '1', name: '系统管理员', disabled: true, value: {...}}, ....]
return {
enumsGet: enums.get,
roles
};
}
};
</script>
```
## API
### get
* `get(name: string)` 获取指定名字的枚举
* `get(name: string, key: string)` 获取指定名字及键枚举默认值
* `get(name: string, opt: {extend: Array<Object>})` 获取指定名字的自定义格式枚举，[查看extend配置](#extend配置)
* `get(name: string, key: string, opt: {dir: string})` 获取指定名字及键枚举[dir规则](#dir规则)的值
```js
get('status')
get('status', '1')
get('status', {
extend: [
{
key: 'name',
dir: 'value',
},
{
key: 'disabled',
transfer: item => item === '0'
}
]
})
get('status', '1', {dir: 'value'})
```
### push
动态添加枚举，重复添加会覆盖
* `push(name: string, _enum: Array<Array>)`
* `push(name: string, _enum: Array<Object>, opt?: Object)`
* opt.keyName 指定key的取值属性，默认是key
* opt.valueName 指定value的取值属性
枚举项为数组，枚举项的[0]解析为key，枚举项的[1]解析为value
枚举项为对象时，根据opt配置keyName、valueName取枚举项属性值分别作为key和value，`如果valueName未设置则value就是枚举项`
### remove
* remove(name: string)
移除指定的枚举
### concat
基于现有的枚举，连接上新的枚举后返回新的枚举
* `concat(name: string, _enum: Array<Array|Object>, opt?: Object))`
* opt.keyName 指定key的取值属性，默认是key
* opt.valueName 指定value的取值属性
* opt.before 是否添加在现有的之前，默认是false
* opt.extend：返回的枚举[extend配置](#extend配置)
### convert
将传入的枚举格式转换为{key, value}的形式
* `convert(name: string, _enum: Array<Array|Object>, opt?: Object))`
* opt.keyName 指定key的取值属性，默认是key
* opt.valueName 指定value的取值属性
### extend配置
扩展枚举项属性的配置
* `extend: Array<Object>`
* `key` 指定扩展的属性名
* `dir` 指定该属性的取值路径
* `transfer(item: {key: any, value: any})` 转换函数，参数未枚举项，返回就是该属性的值
::: tip
同时设置[dir](#dir规则)和transfer，transfer优先
:::
```js
get('status', {
extend: [
{
key: 'name',
dir: 'value',
},
{
key: 'disabled',
transfer: item => item.key === '0'
}
]
})
```
### dir规则
dir是指定枚举项value的取值方式，规则如下：
* 对象属性 `A`、`A.B`
* 数组 `[0]`、`[0][1]`
* 混合 `A[0]`、`[0].A`、`A[0].B`
```js
// 假如枚举项value的结构如下
const user = {
age: 18,
name: 'aring',
role: [
{
id: 1,
name: '管理员'
},
{
id: 2,
name: '业务操作员'
}
]
}
// 那么规则解析是：
dir value
'age' => 18
'role[0]' => {id: 1, name: '管理员'}
'role[1].id' => 2
```
::: tip
枚举项value如果是基本类型，则规则不生效，value就是当前值
:::

32
docs/reference/plugin/plugins/icon.md Normal file
View File

@ -0,0 +1,32 @@
# @fesjs/plugin-icon
## 介绍
提供以 `component` 的方式，直接使用 svg icon 的能力。
## 启用方式
在 `package.json` 中引入依赖：
```json
{
"dependencies": {
"@fesjs/fes": "^2.0.0",
"@fesjs/plugin-icon": "^2.0.0"
},
}
```
## 使用
新建 `src/icons` 目录，将 svg 文件放入其中，在 `component` 中引用：
```jsx
<fes-icon type="iconName" />
```
### 属性
| 属性 | 说明 | 类型 |
| :-----| :---- | :---- |
| type | svg 文件名 | `string` |
| spin | 是否无限旋转 | `boolean` |
| rotate | 旋转角度 | `number` |

6
docs/reference/plugin/plugins/jest.md Normal file
View File

@ -0,0 +1,6 @@
# @fesjs/plugin-jest
## 启用方式
## 配置
## 命令

188
docs/reference/plugin/plugins/layout.md Normal file
View File

@ -0,0 +1,188 @@
# @fesjs/plugin-layout
## 介绍
为了进一步降低研发成本，我们尝试将布局通过 fes 插件的方式内置，只需通过简单的配置即可拥有布局，包括导航以及侧边栏。从而做到用户无需关心布局。
- 侧边栏菜单数据根据路由中的配置自动生成。
- 布局，提供 `side`、 `top`、`mixin` 三种布局。
- 主题，提供 `light`、`dark` 两种主题。
- 默认实现对路由的 404、403 处理。
- 搭配 [@fesjs/plugin-access](./access.html) 插件使用，可以完成对路由的权限控制。
- 搭配 [@fesjs/plugin-loacle](./locale.html) 插件使用，提供切换语言的能力。
- 支持自定义头部区域。
- 可配置页面是否需要 layout。
## 布局类型
默认是 `side`
### side
![side](/side.png)
### top
![top](/top.png)
### mixin
![mixin](/mixin.png)
## 启用方式
在 `package.json` 中引入依赖：
```json
{
"dependencies": {
"@fesjs/fes": "^2.0.0",
"@fesjs/plugin-layout": "^2.0.0"
},
}
```
### 页面禁用布局
Fes.js 渲染路由时，如果路由元信息存在配置 `layout` 为 `false`，则表示禁用此配置，用户只需要如下配置：
```vue
<config>
{
"layout": false
}
</config>
<script>
</script>
```
## 配置
### 编译时配置
在 `.fes.js` 中配置：
```js
export default {
layout: {
title: "Fes.js",
footer: 'Created by MumbelFe',
multiTabs: false,
menus: [{
name: 'index'
}, {
name: 'onepiece'
}, {
name: 'store'
}, {
name: 'simpleList'
}]
},
```
#### title
- **类型**：`String`
- **默认值**：`name` in package.json
- **详情**：产品名，会显示在 Logo 旁边。
#### logo
- **类型**：`String`
- **默认值**：默认提供 fes.js 的 Logo
- **详情**：Logo，会显示在布局上。
#### locale
- **类型**：`boolean`
- **默认值**：`false`
- **详情**：是否显示语言选择框。
#### multiTabs
- **类型**：`boolean`
- **默认值**：`false`
- **详情**：是否开启多页。
#### menus
- **类型**：`Array`
- **默认值**：`[]`
- **详情**：菜单配置，子项具体配置如下：
- **name**：菜单的名称。通过匹配 `name` 和路由元信息 [meta](http://localhost:8080/zh/guide/route.html#%E6%89%A9%E5%B1%95%E8%B7%AF%E7%94%B1%E5%85%83%E4%BF%A1%E6%81%AF) 中的 `name`，把菜单和路由关联起来，然后使用路由元信息补充菜单配置，比如 `title`、`path` 等。
- **path**：菜单的路径，可配置第三方地址。
- **title**：菜单的标题。
- **children**：子菜单配置。
### 运行时配置
在 `app.js` 中配置：
```js
import UserCenter from '@/components/UserCenter';
export const layout = {
customHeader: <UserCenter />
};
```
#### customHeader
- **类型**：Vue Component
- **默认值**：`null`
- **详情**：布局的 Header 部位提供组件自定义功能。
#### unAccessHandler
- **类型**：`Function`
- **默认值**：`null`
- **详情**：
当进入某个路由时，如果路由对应的页面不属于可见资源列表，则会暂停进入，调用 `unAccessHandler` 函数。
- **参数**
- router：createRouter 创建的路由实例
- to： 准备进入的路由
- from：离开的路由
- next： [next函数](https://next.router.vuejs.org/zh/guide/advanced/navigation-guards.html#%E5%8F%AF%E9%80%89%E7%9A%84%E7%AC%AC%E4%B8%89%E4%B8%AA%E5%8F%82%E6%95%B0-next)
比如：
```js
export const access = {
unAccessHandler({ to, next }) {
const accesssIds = accessApi.getAccess();
if (to.path === '/404') {
accessApi.setAccess(accesssIds.concat(['/404']));
return next('/404');
}
if (!accesssIds.includes('/403')) {
accessApi.setAccess(accesssIds.concat(['/403']));
}
next('/403');
}
};
```
#### noFoundHandler
- **类型**：函数
- **默认值**：null
- **详情**：
当进入某个路由时，如果路由对应的页面不存在，则会调用 `noFoundHandler` 函数。
- **参数**
- router：createRouter 创建的路由实例
- to： 准备进入的路由
- from：离开的路由
- next： [next函数](https://next.router.vuejs.org/zh/guide/advanced/navigation-guards.html#%E5%8F%AF%E9%80%89%E7%9A%84%E7%AC%AC%E4%B8%89%E4%B8%AA%E5%8F%82%E6%95%B0-next)
比如：
```js
export const access = {
noFoundHandler({ next }) {
const accesssIds = accessApi.getAccess();
if (!accesssIds.includes('/404')) {
accessApi.setAccess(accesssIds.concat(['/404']));
}
next('/404');
}
};
```

202
docs/reference/plugin/plugins/locale.md Normal file
View File

@ -0,0 +1,202 @@
# @fesjs/plugin-locale
## 介绍
国际化插件，基于 [Vue I18n](https://github.com/intlify/vue-i18n-next)，用于解决 i18n 问题。
## 启用方式
在 `package.json` 中引入依赖：
```json
{
"dependencies": {
"@fesjs/fes": "^2.0.0",
"@fesjs/plugin-locale": "^2.0.0"
},
}
```
## 配置
### 约定式配置
Fes.js 约定如下目录，项目就拥有了 `zh-CN` 与 `en-US` 国际化语言切换：
```
src
├── locales
│ ├── zh-CN.js
│ └── en-US.js
└── pages
│ └── index.vue
└── app.js
```
多语言文件的命名规范：`<lang>-<COUNTRY>.js`
多语言文件的内容规范：键值组成的字面量，如下：
```js
// src/locales/zh-CN.js
export default {
menu: {
interface: '接口'
},
overview: '概述',
i18n: {
internationalization: '国际化，基于',
achieve: '实现。',
ui: 'UI组件'
}
};
```
```js
// src/locales/zh-CN.js
export default {
menu: {
interface: 'interface'
},
overview: 'Overview',
i18n: {
internationalization: 'internationalization，base on',
achieve: 'to achieve.',
ui: 'UI components'
}
};
```
想了解更多语言信息配置、匹配规则，请参考 [Vue I18n](https://vue-i18n.intlify.dev/guide/essentials/syntax.html) 文档。
### 编译时配置
在执行 `fes dev` 或者 `fes build` 时，通过此配置生成运行时的代码，在配置文件`.fes.js` 中配置：
```js
export default {
locale: {
}
}
```
默认配置为：
```js
export default {
locale: {
locale: 'zh-CN', // default locale
fallbackLocale: 'zh-CN', // set fallback locale
baseNavigator: true, // 开启浏览器语言检测
share: true, // 用户是否需要手动改变语言
}
}
```
所有配置项如下：
#### locale
- **类型**：`String`
- **默认值**：`zh-CN`
- **详情**：当前的语言。
#### fallbackLocale
- **类型**：`String`
- **默认值**：`zh-CN`
- **详情**：兜底的语言，如果当前语言找不到配置，则使用默认语言，需要保证默认语言配置文件存在。
#### baseNavigator
- **类型**：`Boolean`
- **默认值**：`true`
- **详情**：开启浏览器语言检测。
默认情况下，当前语言环境的识别按照：`localStorage` 中 `fes_locale` 值 > 浏览器检测 > `default` 设置的默认语言 > `zh-CN` 中文。
#### share
- **类型**：`Boolean`
- **默认值**：`true`
- **详情**：是否共享API，共享语言选择器 `{ SelectLang } `，其他插件可以获取到共享内容。
比如：
```js
import { plugin } from "@@/core/coreExports";
const localeShared = plugin.getShared("locale");
```
### 运行时配置
暂无。
## API
### locale
插件 API 通过 `@fesjs/fes` 导出：
```js
import { locale } from '@fesjs/fes'
```
#### locale.messages
- **类型**：`Object`
- **详情**：当前的配置的语言信息。
#### locale.setLocale
- **类型**：`Function`
- **详情**：设置当前的语言。
- **参数**：
- locale，语言的名称，应该是符合 `<lang>-<COUNTRY>` 规范的名称。
- **返回值**：`null`
```js
import { locale } from '@fesjs/fes';
locale.setLocale({ locale: 'en-US' });
```
#### locale.addLocale
- **类型**：`Function`
- **详情**：手动添加语言配置。
- **参数**：
- locale，语言的名称，符合 `<lang>-<COUNTRY>` 规范的名称。
- messages, 语言信息。
- **返回值**：`null`
```js
import { locale } from '@fesjs/fes'
locale.addLocale({ locale: 'ja-JP', messages: { test: 'テスト' } });
```
#### locale.getAllLocales
- **类型**：`Function`
- **详情**：获取当前获得所有国际化文件的列表，默认会在 locales 文件夹下寻找类似 `en-US.js` 文件。
- **参数**：null
- **返回值**：`Array`
```js
import { locale } from '@fesjs/fes';
console.log(locale.getAllLocales());
// ["en-US", "id-ID", "ja-JP", "pt-BR", "zh-CN", "zh-TW"]
```
### useI18n
Composition API, 只能在 `setup` 函数中使用，更多细节参考 [Vue I18n](https://vue-i18n.intlify.dev/api/composition.html#usei18n)。
举个例子：
```vue
<template>
<form>
<label>{{ t('language') }}</label>
</form>
<p>message: {{ t('hello') }}</p>
</template>
<script>
import { useI18n } from '@fesjs/fes'
export default {
setup() {
const { t } = useI18n()
// Something to do ...
return { ..., t }
}
}
</script>
```
`useI18n()`返回结果是 [Composer](https://vue-i18n.intlify.dev/api/composition.html#composer)，提供类似 `t`、`n`、`d` 等转换函数，在模板中使用。

8
docs/reference/plugin/plugins/model.md Normal file
View File

@ -0,0 +1,8 @@
# @fesjs/plugin-model
## 启用方式
## 配置
## API

157
docs/reference/plugin/plugins/request.md Normal file
View File

@ -0,0 +1,157 @@
# @fesjs/plugin-request
基于 axios 封装的 request，内置防止重复请求、请求节流、错误处理等功能。
## 启用方式
在 `package.json` 中引入依赖：
```json
{
"dependencies": {
"@fesjs/fes": "^2.0.0",
"@fesjs/plugin-request": "^2.0.0"
},
}
```
## 配置
### 构建时配置
```js
export default {
request: {
dataField: 'result',
},
}
```
#### dataField
- 类型： `string`
- 默认值： `''`
- 详情：
`dataField` 对应接口统一格式中的数据字段，比如接口如果统一的规范是 `{ success: boolean, result: any}` ，那么就不需要配置，这样你通过 `useRequest` 消费的时候会生成一个默认的 `formatResult`，直接返回 `result` 中的数据，方便使用。如果你的后端接口不符合这个规范，可以自行配置 `dataField`。配置为 `''`（空字符串）的时候不做处理。
### 运行时配置
在 `app.js` 中进行运行时配置。
```js
export const request = {
// 格式化 response.data (只有 response.data 类型为 object 才会调用)
responseDataAdaptor: (data) => {
},
// 请求拦截器
requestInterceptors: [],
// 相应拦截器
responseInterceptors: [],
// 错误处理
// 内部以 reponse.data.code === '0' 判断请求是否成功
// 若使用其他字段判断，可以使用 responseDataAdaptor 对响应数据进行格式
errorHandler: {
11199: (response) => {
},
404: (error) => {
}
},
// 其他 axios 配置
...otherConfigs
}
```
## 使用
### 发起一个普通 post 请求
```js
import {request} from '@fesjs/fes';
request('/api/login', {
username: 'robby',
password: '123456'
}).then((res) => {
// do something
}).catch((err) => {
// 处理异常
})
```
### 请求节流
```js
import {request} from '@fesjs/fes';
request('/api/login', {
username: 'robby',
password: '123456'
}, {
throttle: 1000, // 1 秒内只能发起一次请求
}).then((res) => {
// do something
}).catch((err) => {
// 处理异常
})
```
### 请求缓存
```js
import {request} from '@fesjs/fes';
request('/api/login', {
username: 'robby',
password: '123456'
}, {
cache: {
cacheType: 'ram', // ram: 内存，session: sessionStorage，local：localStorage
cacheTime: 1000 * 60 * 3 // 缓存时间，默认3min
},
}).then((res) => {
// do something
}).catch((err) => {
// 处理异常
})
```
若 `cache` 传 `true`，则默认使用 `ram` 缓存类型，缓存时间 3min。
### 结合 use 使用
```js
import {useRequest} from '@fesjs/fes';
export default {
setup() {
const {loading, data, error} = useRequest('/api/login', {
username: 'robby',
password: '123456'
})
return {
loading,
data,
error
}
}
}
```
## API
### request
- **类型**：函数
- **详情**：请求后端接口
- **参数**：
- url: 后端接口 url
- data: 参数
- options: 配置（ 支持 axios 所有配置）
- **返回值**: Promise
### useRequest
request 的封装，返回响应式 `loading`、`error`、 `data`

62
docs/reference/plugin/plugins/vuex.md Normal file
View File

@ -0,0 +1,62 @@
# @fesjs/plugin-vuex
## 介绍
集成vuex插件
增强vuex，导出所有的mutations、actions和getter的事件类型，编辑器提示
约定模式，module和plugin定义放在sotres目录下，文件名包含plugin被解析为插件，无需额外配置，定义即可用。
::: tip
vuex的提供的api直接导入使用
:::
## 启用方式
在 `package.json` 中引入依赖：
```json
{
"dependencies": {
"@fesjs/fes": "^2.0.0",
"@fesjs/plugin-vuex": "^2.0.0"
}
}
```
## 配置
在 `.fes.js` 中配置：
```js
export default {
vuex: {
strict: true // 开启严格模式
}
}
```
## 场景使用
vuex定义模块之后，使用getter、mutation、action都是通过传入字符路径，如：
```js
import { useStore } from 'vuex';
const store = useStore();
store.getters['user/address']
store.commit('counter/increment')
store.dispatch('user/login')
```
使用该插件，可以利用导出的事件类型，如：
```js
import { useStore } from 'vuex';
import { MUTATION_TYPES, GETTER_TYPES, ACTION_TYPES } from '@fesjs/fes';
const store = useStore();
store.getters[GETTER_TYPES.user.address]
store.commit(MUTATION_TYPES.counter.increment)
store.dispatch(ACTION_TYPES.user.login)
```
## API
### MUTATION_TYPES
* 类型 `Object`
* mutation的所有事件类型
### GETTER_TYPES
* 类型 `Object`
* getter的所有方法名
### ACTION_TYPES
* 类型 `Object`
* action的所有事件类型

3
docs/reference/plugin/pwa-popup.md
View File

@ -1,3 +0,0 @@
# pwa-popup
> TODO

3
docs/reference/plugin/pwa.md
View File

@ -1,3 +0,0 @@
# pwa
> TODO

3
docs/reference/theme-api.md
View File

@ -1,3 +0,0 @@
# Theme API
> TODO