From 54748f4306d60929abe888b11f8f6e6956fe3e4b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E4=B8=87=E7=BA=AF?= Date: Fri, 5 Mar 2021 19:10:39 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=20=E5=A4=8D=E5=88=B6=E4=B8=AD=E6=96=87?= =?UTF-8?q?=E6=96=87=E6=A1=A3=E5=88=B0=E8=8B=B1=E6=96=87=E7=9B=AE=E5=BD=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/.vuepress/configs/navbar/en.ts | 86 +-- docs/.vuepress/configs/sidebar/en.ts | 103 ++-- docs/README.md | 71 ++- docs/contributing.md | 108 ---- docs/guide/README.md | 76 ++- docs/guide/advanced/markdown.md | 102 ---- docs/guide/advanced/plugin.md | 3 - docs/guide/advanced/theme.md | 3 - docs/guide/assets.md | 104 ---- docs/guide/bundler.md | 3 - docs/guide/config.md | 79 +++ docs/guide/configuration.md | 84 --- docs/guide/contributing.md | 70 +++ docs/guide/deployment.md | 205 ------- docs/guide/directory-structure.md | 67 +++ docs/guide/env.md | 109 ++++ docs/guide/faq.md | 1 + docs/guide/getting-started.md | 189 ++++-- docs/guide/i18n.md | 70 --- docs/guide/markdown.md | 366 ----------- docs/guide/mock.md | 183 ++++++ docs/guide/page.md | 55 -- docs/guide/plugin.md | 92 ++- docs/guide/route.md | 259 ++++++++ docs/guide/template.md | 53 ++ docs/guide/theme.md | 52 -- docs/reference/api.md | 1 + docs/reference/api/README.md | 182 ++++++ docs/reference/bundler/vite.md | 3 - docs/reference/bundler/webpack.md | 3 - docs/reference/cli.md | 18 +- docs/reference/cli/README.md | 175 ++++++ docs/reference/components.md | 56 -- docs/reference/config.md | 574 ------------------ docs/reference/config/README.md | 339 +++++++++++ docs/reference/default-theme/components.md | 106 ---- docs/reference/default-theme/config.md | 603 ------------------- docs/reference/default-theme/frontmatter.md | 252 -------- docs/reference/default-theme/markdown.md | 124 ---- docs/reference/frontmatter.md | 165 ----- docs/reference/plugin-api.md | 285 --------- docs/reference/plugin/README.md | 12 +- docs/reference/plugin/active-header-links.md | 3 - docs/reference/plugin/api.md | 1 + docs/reference/plugin/back-to-top.md | 3 - docs/reference/plugin/container.md | 3 - docs/reference/plugin/debug.md | 3 - docs/reference/plugin/docsearch.md | 3 - docs/reference/plugin/git.md | 3 - docs/reference/plugin/google-analytics.md | 3 - docs/reference/plugin/medium-zoom.md | 3 - docs/reference/plugin/nprogress.md | 3 - docs/reference/plugin/palette-stylus.md | 3 - docs/reference/plugin/plugins/access.md | 254 ++++++++ docs/reference/plugin/plugins/enums.md | 226 +++++++ docs/reference/plugin/plugins/icon.md | 32 + docs/reference/plugin/plugins/jest.md | 6 + docs/reference/plugin/plugins/layout.md | 188 ++++++ docs/reference/plugin/plugins/locale.md | 202 +++++++ docs/reference/plugin/plugins/model.md | 8 + docs/reference/plugin/plugins/request.md | 157 +++++ docs/reference/plugin/plugins/vuex.md | 62 ++ docs/reference/plugin/pwa-popup.md | 3 - docs/reference/plugin/pwa.md | 3 - docs/reference/theme-api.md | 3 - 65 files changed, 3028 insertions(+), 3638 deletions(-) delete mode 100644 docs/contributing.md delete mode 100644 docs/guide/advanced/markdown.md delete mode 100644 docs/guide/advanced/plugin.md delete mode 100644 docs/guide/advanced/theme.md delete mode 100644 docs/guide/assets.md delete mode 100644 docs/guide/bundler.md create mode 100644 docs/guide/config.md delete mode 100644 docs/guide/configuration.md create mode 100644 docs/guide/contributing.md delete mode 100644 docs/guide/deployment.md create mode 100644 docs/guide/directory-structure.md create mode 100644 docs/guide/env.md create mode 100644 docs/guide/faq.md delete mode 100644 docs/guide/i18n.md delete mode 100644 docs/guide/markdown.md create mode 100644 docs/guide/mock.md delete mode 100644 docs/guide/page.md create mode 100644 docs/guide/route.md create mode 100644 docs/guide/template.md delete mode 100644 docs/guide/theme.md create mode 100644 docs/reference/api.md create mode 100644 docs/reference/api/README.md delete mode 100644 docs/reference/bundler/vite.md delete mode 100644 docs/reference/bundler/webpack.md create mode 100644 docs/reference/cli/README.md delete mode 100644 docs/reference/components.md delete mode 100644 docs/reference/config.md create mode 100644 docs/reference/config/README.md delete mode 100644 docs/reference/default-theme/components.md delete mode 100644 docs/reference/default-theme/config.md delete mode 100644 docs/reference/default-theme/frontmatter.md delete mode 100644 docs/reference/default-theme/markdown.md delete mode 100644 docs/reference/frontmatter.md delete mode 100644 docs/reference/plugin-api.md delete mode 100644 docs/reference/plugin/active-header-links.md create mode 100644 docs/reference/plugin/api.md delete mode 100644 docs/reference/plugin/back-to-top.md delete mode 100644 docs/reference/plugin/container.md delete mode 100644 docs/reference/plugin/debug.md delete mode 100644 docs/reference/plugin/docsearch.md delete mode 100644 docs/reference/plugin/git.md delete mode 100644 docs/reference/plugin/google-analytics.md delete mode 100644 docs/reference/plugin/medium-zoom.md delete mode 100644 docs/reference/plugin/nprogress.md delete mode 100644 docs/reference/plugin/palette-stylus.md create mode 100644 docs/reference/plugin/plugins/access.md create mode 100644 docs/reference/plugin/plugins/enums.md create mode 100644 docs/reference/plugin/plugins/icon.md create mode 100644 docs/reference/plugin/plugins/jest.md create mode 100644 docs/reference/plugin/plugins/layout.md create mode 100644 docs/reference/plugin/plugins/locale.md create mode 100644 docs/reference/plugin/plugins/model.md create mode 100644 docs/reference/plugin/plugins/request.md create mode 100644 docs/reference/plugin/plugins/vuex.md delete mode 100644 docs/reference/plugin/pwa-popup.md delete mode 100644 docs/reference/plugin/pwa.md delete mode 100644 docs/reference/theme-api.md diff --git a/docs/.vuepress/configs/navbar/en.ts b/docs/.vuepress/configs/navbar/en.ts index da41c71a..1de7d98b 100644 --- a/docs/.vuepress/configs/navbar/en.ts +++ b/docs/.vuepress/configs/navbar/en.ts @@ -6,78 +6,32 @@ export const en: NavbarConfig = [ link: '/guide/', }, { - text: 'Reference', - children: [ - { - text: 'VuePress', - children: [ - { - text: 'CLI', - link: '/reference/cli.html', - }, - '/reference/config.md', - '/reference/frontmatter.md', - '/reference/components.md', - '/reference/plugin-api.md', - '/reference/theme-api.md', - ], - }, - { - 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: 'Config', + link: '/reference/config/', }, { - text: 'Learn More', + text: 'API', + link: '/reference/api/', + }, + { + text: 'Plugin', + link: '/reference/plugin/', + }, + { + text: 'CLI', + link: '/reference/cli/', + }, + { + text: 'More', children: [ { - text: 'Advanced', - children: [ - '/guide/advanced/markdown.md', - '/guide/advanced/theme.md', - '/guide/advanced/plugin.md', - ], + text: '更新日志', + link: + 'https://github.com/WeBankFinTech/fes.js/blob/master/CHANGELOG.md', }, { - text: 'Resources', - children: [ - '/contributing.md', - { - text: 'Changelog', - link: - 'https://github.com/vuepress/vuepress-next/blob/main/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/', }, ], }, diff --git a/docs/.vuepress/configs/sidebar/en.ts b/docs/.vuepress/configs/sidebar/en.ts index 970f4435..307af7c2 100644 --- a/docs/.vuepress/configs/sidebar/en.ts +++ b/docs/.vuepress/configs/sidebar/en.ts @@ -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', - '/guide/plugin.md', - '/guide/bundler.md', + '/guide/getting-started.md', ], }, - ], - '/guide/advanced/': [ { isGroup: true, - text: 'Advanced', + text: '基础', children: [ - '/guide/advanced/markdown.md', - '/guide/advanced/theme.md', - '/guide/advanced/plugin.md', - ], + '/guide/directory-structure.md', + '/guide/config.md', + '/guide/route.md', + '/guide/plugin.md', + '/guide/template.md', + '/guide/mock.md', + '/guide/env.md', + ] }, - ], - '/reference/': [ { isGroup: true, - text: 'VuePress Reference', + text: '进阶', children: [ - '/reference/cli.md', - '/reference/config.md', - '/reference/frontmatter.md', - '/reference/components.md', - '/reference/plugin-api.md', - '/reference/theme-api.md', - ], + ] }, + "/guide/contributing.md", + "/guide/faq.md" ], - '/reference/bundler/': [ - { - isGroup: true, - text: 'Bundlers Reference', - children: ['/reference/bundler/webpack.md', '/reference/bundler/vite.md'], - }, + '/reference/config/': [ + '/reference/config/README.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', + ], } diff --git a/docs/README.md b/docs/README.md index ce309142..4ce085d6 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,60 +1,65 @@ --- 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 一样容易 ```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 ``` - + ```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 ``` + +## 反馈 + +| Github Issue | 微信群 | Fes.js开源运营小助手 | +| --- | --- | --- | +| [@fesjs/fes.js/issues](https://github.com/WeBankFinTech/fes.js/issues) | | | + diff --git a/docs/contributing.md b/docs/contributing.md deleted file mode 100644 index 563bf804..00000000 --- a/docs/contributing.md +++ /dev/null @@ -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. diff --git a/docs/guide/README.md b/docs/guide/README.md index 1e9cce4f..8389fd01 100644 --- a/docs/guide/README.md +++ b/docs/guide/README.md @@ -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等插件，可以满足大部分日常开发需求。 + +- :firecracker: __简单__ ，基于Vue.js 3.0，上手简单。贯彻“约定优于配置”思想，设计插件上尽可能用约定替代配置，同时提供统一的插件配置入口，简单简洁又不失灵活。提供一致性的API入口，一致化的体验，学习起来更轻松。 -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. +- 💪 __健壮__ ，只需要关心页面内容，减少写BUG的机会！提供单元测试、覆盖测试能力保障项目质量。 -### VitePress +- :package: __可扩展__ ，借鉴Umi实现了完整的生命周期和插件化机制，插件可以管理项目的编译时和运行时，能力均可以通过插件封装进来，在 Fes.js 中协调有序的运行。 -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. +- 📡 __面向未来__ ，在满足需求的同时，我们也不会停止对新技术的探索。已使用Vue3.0来提升应用性能，已使用webpack5提升构建性能和实现微服务，未来会探索vite等新技术。 -It might not be an appropriate comparison, but you can take VuePress and VitePress as Laravel and Lumen. -### Docsify / Docute +## Fes.js 如何工作？ -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. +### 架构 +![架构](/framework.png "架构") -### Hexo +Fes.js 把大家常用的技术栈封装成一个个插件进行整理，收敛到一起，让大家只用 Fes.js 就可以完成 80% 的日常工作。 -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 支持插件和插件集，通过这张图应该很好理解到他们的关系，通过插件集我们把插件收敛依赖然后支持不同的业务类型。 -### GitBook +### .fes 临时文件 +.fes 临时目录是整个 Fes.js 项目的发动机，你的入口文件、路由等等都在这里，这些是由 fes 内部插件及三方插件生成的。 -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 + + 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。 diff --git a/docs/guide/advanced/markdown.md b/docs/guide/advanced/markdown.md deleted file mode 100644 index b781a528..00000000 --- a/docs/guide/advanced/markdown.md +++ /dev/null @@ -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 ` - - -``` - -**Output** - -_Hello, {{ msg }}_ - - - -_Current count is: {{ count }}_ - - - - - - - - diff --git a/docs/guide/advanced/plugin.md b/docs/guide/advanced/plugin.md deleted file mode 100644 index d0251ed7..00000000 --- a/docs/guide/advanced/plugin.md +++ /dev/null @@ -1,3 +0,0 @@ -# Writing a Plugin - -> TODO diff --git a/docs/guide/advanced/theme.md b/docs/guide/advanced/theme.md deleted file mode 100644 index 89476481..00000000 --- a/docs/guide/advanced/theme.md +++ /dev/null @@ -1,3 +0,0 @@ -# Writing a Theme - -> TODO diff --git a/docs/guide/assets.md b/docs/guide/assets.md deleted file mode 100644 index 5cd1b8b3..00000000 --- a/docs/guide/assets.md +++ /dev/null @@ -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 -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) -::: diff --git a/docs/guide/bundler.md b/docs/guide/bundler.md deleted file mode 100644 index 82ea1f1c..00000000 --- a/docs/guide/bundler.md +++ /dev/null @@ -1,3 +0,0 @@ -# Bundler - -> TODO diff --git a/docs/guide/config.md b/docs/guide/config.md new file mode 100644 index 00000000..206bc963 --- /dev/null +++ b/docs/guide/config.md @@ -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` 文件的配置 +::: \ No newline at end of file diff --git a/docs/guide/configuration.md b/docs/guide/configuration.md deleted file mode 100644 index 0aaf3f66..00000000 --- a/docs/guide/configuration.md +++ /dev/null @@ -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. - - - - -```js -module.exports = { - lang: 'en-US', - title: 'Hello, VuePress!', - description: 'This is my first VuePress site', - - themeConfig: { - logo: 'https://vuejs.org/images/logo.png', - }, -} -``` - - - - - -```ts -import type { UserConfig, DefaultThemeOptions } from 'vuepress' - -const config: UserConfig = { - lang: 'en-US', - title: 'Hello VuePress', - description: 'Just playing around', - - themeConfig: { - logo: 'https://vuejs.org/images/logo.png', - }, -} - -export = config -``` - - - - -::: 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. -::: diff --git a/docs/guide/contributing.md b/docs/guide/contributing.md new file mode 100644 index 00000000..b17a1746 --- /dev/null +++ b/docs/guide/contributing.md @@ -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` \ No newline at end of file diff --git a/docs/guide/deployment.md b/docs/guide/deployment.md deleted file mode 100644 index 5906a27c..00000000 --- a/docs/guide/deployment.md +++ /dev/null @@ -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://.github.io/`, you can omit this step as `base` defaults to `"/"`. - - If you are deploying to `https://.github.io//`, for example your repository is at `https://github.com//`, then set `base` to `"//"`. - -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://.gitlab.io/`, you can omit `base` as it defaults to `"/"`. - - If you are deploying to `https://.gitlab.io//`, for example your repository is at `https://gitlab.com//`, then set `base` to `"//"`. - -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": "" - } -} -``` - -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). diff --git a/docs/guide/directory-structure.md b/docs/guide/directory-structure.md new file mode 100644 index 00000000..321ef685 --- /dev/null +++ b/docs/guide/directory-structure.md @@ -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 +运行时配置文件，可以在这里扩展运行时的能力，比如修改路由等。 \ No newline at end of file diff --git a/docs/guide/env.md b/docs/guide/env.md new file mode 100644 index 00000000..8dfa1ec6 --- /dev/null +++ b/docs/guide/env.md @@ -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) + + + +```bash +yarn add cross-env --dev +cross-env PORT=3000 umi dev +``` + + + + +```bash +npm i cross-env --save-dev +cross-env PORT=3000 umi dev +``` + + + + +### 在 .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` diff --git a/docs/guide/faq.md b/docs/guide/faq.md new file mode 100644 index 00000000..307d253c --- /dev/null +++ b/docs/guide/faq.md @@ -0,0 +1 @@ +# 常见问题 \ No newline at end of file diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md index 1561404b..cfa0cdc0 100644 --- a/docs/guide/getting-started.md +++ b/docs/guide/getting-started.md @@ -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 创建模板 ```bash -git init -yarn init +# 创建模板 +yarn create @fesjs/fes-app myapp ``` @@ -31,20 +45,30 @@ yarn init ```bash -git init -npm init +# 创建模板 +npx @fesjs/create-fes-app myapp ``` -- **Step 3**: Install VuePress locally +如果项目目录 `workspace/myapp` 已经存在，则会提示目录已存在，你可以选择 `Overwrite` 删除目录后重新创建项目，也可以选择 `Merge` 使用模板文件覆盖当前目录文件。 +![目录已存在提示](/pickTemplateTip.png) + +如果项目目录 `workspace/myapp` 不存在，你会被提示选取一个 template。你可以选默认适用于中后台前端应用的 `PC` 类型，也可以选适用于移动端的 `H5` 类型。 + +![选择模板类型](/pickTemplate.png) + +##### 步骤3 安装依赖 ```bash -yarn add -D vuepress@next +# 进入项目目录 +cd myapp +# 安装依赖 +yarn ``` @@ -52,43 +76,31 @@ yarn add -D vuepress@next ```bash -npm install -D vuepress@next +# 进入项目目录 +cd myapp +# 安装依赖 +npm i ``` -- **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 - +## 启动项目 ```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 ``` @@ -96,12 +108,85 @@ yarn docs:dev ```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 ``` - 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) + + +## 部署发布 + +### 构建 + + + +```bash +# 构建 +yarn build + +yarn run v1.22.4 +$ fes build + +✔ Webpack + Compiled successfully in 45.37s + +✨ Done in 48.87s. +``` + + + + + +```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 +``` + + + + +构建产物默认生成到 ./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 目录部署到服务器上。 \ No newline at end of file diff --git a/docs/guide/i18n.md b/docs/guide/i18n.md deleted file mode 100644 index 18ed8f86..00000000 --- a/docs/guide/i18n.md +++ /dev/null @@ -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) -::: diff --git a/docs/guide/markdown.md b/docs/guide/markdown.md deleted file mode 100644 index b67f60be..00000000 --- a/docs/guide/markdown.md +++ /dev/null @@ -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 -Home -Guide -Getting Started -markdown.links -GitHub -``` - -**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 `` 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 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 - -1 + 2 + 3 = {{ 1 + 2 + 3 }} -``` - -```md:no-v-pre - -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 - -1 + 2 + 3 = {{ 1 + 2 + 3 }} -``` - -```md:no-v-pre - -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: {{ i }} -``` - -**Output** - -One plus one equals: {{ 1 + 1 }} - - span: {{ i }} - -### Components - -You can use Vue components directly in Markdown. - -**Input** - -```md -This is default theme built-in `` component -``` - -**Output** - -This is default theme built-in `` component - -::: 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. -::: diff --git a/docs/guide/mock.md b/docs/guide/mock.md new file mode 100644 index 00000000..a2147e6c --- /dev/null +++ b/docs/guide/mock.md @@ -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, +}; +``` diff --git a/docs/guide/page.md b/docs/guide/page.md deleted file mode 100644 index b67d9918..00000000 --- a/docs/guide/page.md +++ /dev/null @@ -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 `