From 1bb4e40da5d7df94b109e898a64f25fdee292525 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E4=B8=87=E7=BA=AF?= Date: Mon, 1 Mar 2021 16:46:32 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=20=E6=95=B4=E7=90=86=E4=B8=AD=E6=96=87?= =?UTF-8?q?=E6=96=87=E6=A1=A3=E7=BB=93=E6=9E=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/.vuepress/config.ts | 9 +- docs/.vuepress/configs/navbar/zh.ts | 95 +-- docs/.vuepress/configs/sidebar/zh.ts | 106 ++- docs/zh/guide/advanced/markdown.md | 102 --- docs/zh/guide/advanced/plugin.md | 3 - docs/zh/guide/advanced/theme.md | 3 - docs/zh/guide/assets.md | 104 --- docs/zh/guide/bundler.md | 3 - docs/zh/guide/configuration.md | 84 --- docs/zh/{ => guide}/contributing.md | 4 - docs/zh/guide/deployment.md | 239 ------- docs/zh/guide/faq.md | 1 + docs/zh/guide/i18n.md | 70 -- docs/zh/guide/markdown.md | 369 ----------- docs/zh/guide/page.md | 55 -- docs/zh/guide/plugin.md | 45 -- docs/zh/guide/theme.md | 52 -- docs/zh/reference/api.md | 1 + docs/zh/reference/api/README.md | 5 + docs/zh/reference/bundler/vite.md | 3 - docs/zh/reference/bundler/webpack.md | 3 - docs/zh/reference/cli/README.md | 10 + docs/zh/reference/components.md | 56 -- .../reference/{config.md => config/README.md} | 4 + docs/zh/reference/default-theme/components.md | 106 --- docs/zh/reference/default-theme/config.md | 603 ------------------ .../zh/reference/default-theme/frontmatter.md | 253 -------- docs/zh/reference/default-theme/markdown.md | 124 ---- docs/zh/reference/frontmatter.md | 165 ----- docs/zh/reference/plugin-api.md | 285 --------- docs/zh/reference/plugin/README.md | 4 +- .../reference/plugin/active-header-links.md | 3 - docs/zh/reference/plugin/api.md | 1 + docs/zh/reference/plugin/back-to-top.md | 3 - docs/zh/reference/plugin/container.md | 3 - docs/zh/reference/plugin/debug.md | 3 - docs/zh/reference/plugin/docsearch.md | 3 - docs/zh/reference/plugin/git.md | 3 - docs/zh/reference/plugin/google-analytics.md | 3 - docs/zh/reference/plugin/medium-zoom.md | 3 - docs/zh/reference/plugin/nprogress.md | 3 - docs/zh/reference/plugin/palette-stylus.md | 3 - docs/zh/reference/plugin/plugins/access.md | 1 + docs/zh/reference/plugin/plugins/enums.md | 1 + docs/zh/reference/plugin/plugins/icon.md | 1 + docs/zh/reference/plugin/plugins/jest.md | 1 + docs/zh/reference/plugin/plugins/layout.md | 1 + docs/zh/reference/plugin/plugins/locale.md | 1 + docs/zh/reference/plugin/plugins/model.md | 1 + docs/zh/reference/plugin/plugins/request.md | 1 + docs/zh/reference/plugin/plugins/vuex.md | 1 + docs/zh/reference/plugin/pwa-popup.md | 3 - docs/zh/reference/plugin/pwa.md | 3 - docs/zh/reference/theme-api.md | 3 - packages/fes-plugin-layout/src/index.js | 2 +- 55 files changed, 101 insertions(+), 2916 deletions(-) delete mode 100644 docs/zh/guide/advanced/markdown.md delete mode 100644 docs/zh/guide/advanced/plugin.md delete mode 100644 docs/zh/guide/advanced/theme.md delete mode 100644 docs/zh/guide/assets.md delete mode 100644 docs/zh/guide/bundler.md delete mode 100644 docs/zh/guide/configuration.md rename docs/zh/{ => guide}/contributing.md (99%) delete mode 100644 docs/zh/guide/deployment.md create mode 100644 docs/zh/guide/faq.md delete mode 100644 docs/zh/guide/i18n.md delete mode 100644 docs/zh/guide/markdown.md delete mode 100644 docs/zh/guide/page.md delete mode 100644 docs/zh/guide/plugin.md delete mode 100644 docs/zh/guide/theme.md create mode 100644 docs/zh/reference/api.md create mode 100644 docs/zh/reference/api/README.md delete mode 100644 docs/zh/reference/bundler/vite.md delete mode 100644 docs/zh/reference/bundler/webpack.md create mode 100644 docs/zh/reference/cli/README.md delete mode 100644 docs/zh/reference/components.md rename docs/zh/reference/{config.md => config/README.md} (99%) delete mode 100644 docs/zh/reference/default-theme/components.md delete mode 100644 docs/zh/reference/default-theme/config.md delete mode 100644 docs/zh/reference/default-theme/frontmatter.md delete mode 100644 docs/zh/reference/default-theme/markdown.md delete mode 100644 docs/zh/reference/frontmatter.md delete mode 100644 docs/zh/reference/plugin-api.md delete mode 100644 docs/zh/reference/plugin/active-header-links.md create mode 100644 docs/zh/reference/plugin/api.md delete mode 100644 docs/zh/reference/plugin/back-to-top.md delete mode 100644 docs/zh/reference/plugin/container.md delete mode 100644 docs/zh/reference/plugin/debug.md delete mode 100644 docs/zh/reference/plugin/docsearch.md delete mode 100644 docs/zh/reference/plugin/git.md delete mode 100644 docs/zh/reference/plugin/google-analytics.md delete mode 100644 docs/zh/reference/plugin/medium-zoom.md delete mode 100644 docs/zh/reference/plugin/nprogress.md delete mode 100644 docs/zh/reference/plugin/palette-stylus.md create mode 100644 docs/zh/reference/plugin/plugins/access.md create mode 100644 docs/zh/reference/plugin/plugins/enums.md create mode 100644 docs/zh/reference/plugin/plugins/icon.md create mode 100644 docs/zh/reference/plugin/plugins/jest.md create mode 100644 docs/zh/reference/plugin/plugins/layout.md create mode 100644 docs/zh/reference/plugin/plugins/locale.md create mode 100644 docs/zh/reference/plugin/plugins/model.md create mode 100644 docs/zh/reference/plugin/plugins/request.md create mode 100644 docs/zh/reference/plugin/plugins/vuex.md delete mode 100644 docs/zh/reference/plugin/pwa-popup.md delete mode 100644 docs/zh/reference/plugin/pwa.md delete mode 100644 docs/zh/reference/theme-api.md diff --git a/docs/.vuepress/config.ts b/docs/.vuepress/config.ts index 7d2a2144..0e3d4078 100644 --- a/docs/.vuepress/config.ts +++ b/docs/.vuepress/config.ts @@ -91,11 +91,12 @@ const config: UserConfig = { [ '@vuepress/plugin-docsearch', { - // TODO: create algolia index for vuepress-next - // apiKey: '', - // appId: '', - // indexName: '', + apiKey: '', + indexName: '', locales: { + '/': { + placeholder: 'Search Documentation', + }, '/zh/': { placeholder: '搜索文档', }, diff --git a/docs/.vuepress/configs/navbar/zh.ts b/docs/.vuepress/configs/navbar/zh.ts index 9c60a244..6d7da7a9 100644 --- a/docs/.vuepress/configs/navbar/zh.ts +++ b/docs/.vuepress/configs/navbar/zh.ts @@ -7,91 +7,32 @@ export const zh: NavbarConfig = [ }, { text: '配置', - link: '/zh/reference/config', + link: '/zh/reference/config/', }, { text: 'API', - link: '/zh/reference/api', + link: '/zh/reference/api/', }, { text: '插件', - link: '/zh/reference/plugin', + link: '/zh/reference/plugin/', }, { text: 'CLI', - link: '/zh/reference/cli', + link: '/zh/reference/cli/', + }, + { + text: '了解更多', + children: [ + { + text: '更新日志', + link: + 'https://github.com/WeBankFinTech/fes.js/blob/master/CHANGELOG.md', + }, + { + text: 'v1 文档', + link: 'https://webank.gitee.io/fes.js-v0/', + }, + ], }, - // { - // text: '参考', - // children: [ - // { - // text: 'VuePress', - // children: [ - // '/zh/reference/cli.md', - // '/zh/reference/config.md', - // '/zh/reference/frontmatter.md', - // '/zh/reference/components.md', - // '/zh/reference/plugin-api.md', - // '/zh/reference/theme-api.md', - // ], - // }, - // { - // text: '打包工具', - // children: [ - // '/zh/reference/bundler/webpack.md', - // '/zh/reference/bundler/vite.md', - // ], - // }, - // { - // text: '默认主题', - // children: [ - // '/zh/reference/default-theme/config.md', - // '/zh/reference/default-theme/frontmatter.md', - // '/zh/reference/default-theme/components.md', - // '/zh/reference/default-theme/markdown.md', - // ], - // }, - // { - // text: '官方插件', - // link: '/zh/reference/plugin/', - // children: [], - // }, - // ], - // }, - // { - // text: '了解更多', - // children: [ - // { - // text: '深入', - // children: [ - // '/zh/guide/advanced/markdown.md', - // '/zh/guide/advanced/theme.md', - // '/zh/guide/advanced/plugin.md', - // ], - // }, - // { - // text: '其他资源', - // children: [ - // '/zh/contributing.md', - // { - // text: '更新日志', - // link: - // 'https://github.com/vuepress/vuepress-next/blob/main/CHANGELOG.md', - // }, - // { - // text: 'Awesome VuePress', - // link: 'https://github.com/vuepress/awesome-vuepress', - // }, - // { - // text: 'v1 文档', - // link: 'https://v1.vuepress.vuejs.org/zh/', - // }, - // { - // text: 'v0 文档', - // link: 'https://v0.vuepress.vuejs.org/zh/', - // }, - // ], - // }, - // ], - // }, ] diff --git a/docs/.vuepress/configs/sidebar/zh.ts b/docs/.vuepress/configs/sidebar/zh.ts index 22800dc0..3e4f7913 100644 --- a/docs/.vuepress/configs/sidebar/zh.ts +++ b/docs/.vuepress/configs/sidebar/zh.ts @@ -4,87 +4,71 @@ export const zh: SidebarConfig = { '/zh/guide/': [ { isGroup: true, - text: '指南', + text: '介绍', children: [ '/zh/guide/README.md', - '/zh/guide/getting-started.md', - '/zh/guide/configuration.md', - '/zh/guide/page.md', - '/zh/guide/markdown.md', - '/zh/guide/assets.md', - '/zh/guide/i18n.md', - '/zh/guide/deployment.md', - '/zh/guide/theme.md', - '/zh/guide/plugin.md', - '/zh/guide/bundler.md', + '/zh/guide/getting-started.md', ], }, - ], - '/zh/guide/advanced/': [ { isGroup: true, - text: '深入', + text: '基础', children: [ - '/zh/guide/advanced/markdown.md', - '/zh/guide/advanced/theme.md', - '/zh/guide/advanced/plugin.md', - ], + ] }, - ], - '/zh/reference/': [ { isGroup: true, - text: 'VuePress 参考', + text: '进阶', children: [ - '/zh/reference/cli.md', - '/zh/reference/config.md', - '/zh/reference/frontmatter.md', - '/zh/reference/components.md', - '/zh/reference/plugin-api.md', - '/zh/reference/theme-api.md', - ], + ] }, + "/zh/guide/contributing.md", + "/zh/guide/faq.md" ], - '/zh/reference/bundler/': [ - { - isGroup: true, - text: '打包工具参考', - children: [ - '/zh/reference/bundler/webpack.md', - '/zh/reference/bundler/vite.md', - ], - }, + '/zh/reference/config/': [ + '/zh/reference/config/README.md' ], - '/zh/reference/default-theme/': [ - { - isGroup: true, - text: '默认主题参考', - children: [ - '/zh/reference/default-theme/config.md', - '/zh/reference/default-theme/frontmatter.md', - '/zh/reference/default-theme/components.md', - '/zh/reference/default-theme/markdown.md', - ], - }, + '/zh/reference/api/': [ + '/zh/reference/api/README.md' ], '/zh/reference/plugin/': [ { isGroup: true, - text: '官方插件参考', + text: '指南', children: [ - '/zh/reference/plugin/active-header-links.md', - '/zh/reference/plugin/back-to-top.md', - '/zh/reference/plugin/container.md', - '/zh/reference/plugin/debug.md', - '/zh/reference/plugin/docsearch.md', - '/zh/reference/plugin/git.md', - '/zh/reference/plugin/google-analytics.md', - '/zh/reference/plugin/medium-zoom.md', - '/zh/reference/plugin/nprogress.md', - '/zh/reference/plugin/palette-stylus.md', - '/zh/reference/plugin/pwa.md', - '/zh/reference/plugin/pwa-popup.md', + '/zh/reference/plugin/README.md', + ], + }, + { + isGroup: true, + text: 'Presets', + children: [ + ], + }, + { + isGroup: true, + text: 'Plugins', + children: [ + '/zh/reference/plugin/plugins/access.md', + '/zh/reference/plugin/plugins/enums.md', + '/zh/reference/plugin/plugins/icon.md', + '/zh/reference/plugin/plugins/jest.md', + '/zh/reference/plugin/plugins/layout.md', + '/zh/reference/plugin/plugins/locale.md', + '/zh/reference/plugin/plugins/model.md', + '/zh/reference/plugin/plugins/request.md', + '/zh/reference/plugin/plugins/vuex.md', + ], + }, + { + isGroup: true, + text: '插件开发', + children: [ + '/zh/reference/plugin/api.md' ], }, ], + '/zh/reference/cli/': [ + '/zh/reference/cli/README.md', + ], } diff --git a/docs/zh/guide/advanced/markdown.md b/docs/zh/guide/advanced/markdown.md deleted file mode 100644 index 3d5cd073..00000000 --- a/docs/zh/guide/advanced/markdown.md +++ /dev/null @@ -1,102 +0,0 @@ -# Markdown 与 Vue SFC - -每一个 Markdown 文件，首先都会编译为 HTML ，然后转换为一个 Vue 单文件组件 (SFC) 。换句话说，你可以把 Markdown 作为 Vue SFC 来看待： - -- ` - - -``` - -**输出** - -_你好， {{ msg }}_ - - - -_当前计数为： {{ count }}_ - - - - - - - - diff --git a/docs/zh/guide/advanced/plugin.md b/docs/zh/guide/advanced/plugin.md deleted file mode 100644 index 41dce7d7..00000000 --- a/docs/zh/guide/advanced/plugin.md +++ /dev/null @@ -1,3 +0,0 @@ -# 开发插件 - -> TODO diff --git a/docs/zh/guide/advanced/theme.md b/docs/zh/guide/advanced/theme.md deleted file mode 100644 index 85ef24d4..00000000 --- a/docs/zh/guide/advanced/theme.md +++ /dev/null @@ -1,3 +0,0 @@ -# 开发主题 - -> TODO diff --git a/docs/zh/guide/assets.md b/docs/zh/guide/assets.md deleted file mode 100644 index ec11377c..00000000 --- a/docs/zh/guide/assets.md +++ /dev/null @@ -1,104 +0,0 @@ -# 静态资源 - -## 相对路径 - -你可以在你的 Markdown 内容中使用相对路径来引用静态资源： - -```md -![图片](./image.png) -``` - -一般情况下，我们推荐你使用这种方式来引用图片，因为人们通常会把图片放在引用它的 Markdown 文件附近。 - -## Public 文件 - -你可以把一些静态资源放在 Public 目录中，它们会被复制到最终生成的网站的根目录下。 - -默认的 Public 目录是 `.vuepress/public` ，可以通过配置来修改。 - -在下列这些情况中，你可能会用到它： - -- 你可能需要提供一些静态资源，但是它们并不直接被你的 Markdown 文件引用，比如 favicon 和 PWA 图标。 -- 你可能想要托管一些共享的静态资源，甚至可能需要在你的网站外部引用它，比如 Logo 图片。 -- 你可能想在你的 Markdown 内容中通过绝对路径来引入图片。 - -以我们文档的源文件为例，我们把 VuePress 的 Logo 放在了 Public 目录下： - -```bash -└─ docs - ├─ .vuepress - | └─ public - | └─ hero.png # <- Logo 文件 - └─ guide - └─ assets.md # <- 我们在这里 -``` - -我们可以这样在当前页面引用 Logo ： - -**Input** - -```md -![VuePress Logo](/hero.png) -``` - -**Output** - -![VuePress Logo](/hero.png) - -::: tip -配置参考： [public](../reference/config.md#public) -::: - -### Base Helper - -如果你的网站部署在非根路径下，即 [base](../reference/config.md#base) 不是 `"/"` ，你需要把 `base` 添加到 Public 文件的绝对路径前。 - -举例来说，如果你想要把网站部署到 `https://foo.github.io/bar/` ，那么应该把 `base` 设置为 `"/bar/"` ，此时你必须在 Markdown 文件中这样引用 Public 文件： - -```md -![VuePress Logo](/bar/hero.png) -``` - -显然，一旦某一天你修改了 `base`，这样的路径引用将会显得异常脆弱。这也是我们推荐你使用相对路径来引用静态文件的原因。 - -为了解决这个问题，VuePress 提供了内置的一个 Helper `$withBase` ，它可以帮助你生成正确的路径： - -```md -VuePress Logo -``` - -在 Markdown 中使用这个 Helper 会显得有些冗长，因此它可能对主题和插件作者更有帮助。 - -::: tip -配置参考： [base](../reference/config.md#base) -::: - -## 依赖包和路径别名 - -尽管这不是常见用法，但是你可以从依赖包中引用图片： - -```bash -npm install -D package-name -``` - -```md -![来自依赖包的图片](package-name/image.png) -``` - -在配置文件中设置的路径别名也同样支持： - -```js -module.exports = { - alias: { - '@alias': '/path/to/some/dir', - }, -} -``` - -```md -![来自路径别名的图片](@alias/image.png) -``` - -::: tip -配置参考： [alias](../reference/config.md#alias) -::: diff --git a/docs/zh/guide/bundler.md b/docs/zh/guide/bundler.md deleted file mode 100644 index d6659134..00000000 --- a/docs/zh/guide/bundler.md +++ /dev/null @@ -1,3 +0,0 @@ -# 打包工具 - -> TODO diff --git a/docs/zh/guide/configuration.md b/docs/zh/guide/configuration.md deleted file mode 100644 index 681b7e5c..00000000 --- a/docs/zh/guide/configuration.md +++ /dev/null @@ -1,84 +0,0 @@ -# 配置 - -## 配置文件 - -如果没有任何配置，你的 VuePress 站点仅有一些最基础的功能。为了更好地自定义你的网站，让我们首先在你的文档目录下创建一个 `.vuepress` 目录，所有 VuePress 相关的文件都将会被放在这里。你的项目结构可能是这样： - -``` -├─ docs -│ ├─ .vuepress -│ │ └─ config.js -│ └─ README.md -├─ .gitignore -└─ package.json -``` - -VuePress 站点必要的配置文件是 `.vuepress/config.js`，它应该导出一个 JavaScript 对象。如果你使用 TypeScript ，你可以将其替换为 `.vuepress/config.ts` ，以便让 VuePress 配置得到更好的类型提示。 - - - - -```js -module.exports = { - lang: 'zh-CN', - title: '你好， VuePress ！', - description: '这是我的第一个 VuePress 站点', - - themeConfig: { - logo: 'https://vuejs.org/images/logo.png', - }, -} -``` - - - - - -```ts -import type { UserConfig, DefaultThemeOptions } from 'vuepress' - -const config: UserConfig = { - lang: 'zh-CN', - title: '你好， VuePress ！', - description: '这是我的第一个 VuePress 站点', - - themeConfig: { - logo: 'https://vuejs.org/images/logo.png', - }, -} - -export = config -``` - - - - -::: tip -我们接下来会把这个配置对象称为 **VuePress 配置**. -::: - -## 配置作用域 - -你可能已经注意到了，在 VuePress 配置中有一项 `themeConfig` 配置项。 - -在 `themeConfig` 外部的配置项属于 **站点配置** ，而在 `themeConfig` 内部的配置项则属于 **主题配置**。 - -### 站点配置 - -站点配置的意思是，无论你使用什么主题，这些配置项都可以生效。 - -我们知道，每一个站点都应该有它的 `lang`, `title` 和 `description` 等属性，因此 VuePress 内置支持了这些属性的配置。 - -::: tip -前往 [配置参考](../reference/config.md) 查看所有站点配置。 -::: - -### 主题配置 - -主题配置将会被 VuePress 主题来处理，所以它取决于你使用的主题是什么。 - -如果你没有设置 VuePress 配置的 `theme` 配置项，则代表使用的是默认主题。 - -::: tip -前往 [默认主题 > 配置参考](../reference/default-theme/config.md) 查看默认主题的配置。 -::: diff --git a/docs/zh/contributing.md b/docs/zh/guide/contributing.md similarity index 99% rename from docs/zh/contributing.md rename to docs/zh/guide/contributing.md index 26dbc256..5a680bb8 100644 --- a/docs/zh/contributing.md +++ b/docs/zh/guide/contributing.md @@ -1,7 +1,3 @@ ---- -sidebar: auto ---- - # 贡献指南 ## 概览 diff --git a/docs/zh/guide/deployment.md b/docs/zh/guide/deployment.md deleted file mode 100644 index 8e7d6c07..00000000 --- a/docs/zh/guide/deployment.md +++ /dev/null @@ -1,239 +0,0 @@ -# 部署 - -下述的指南基于以下条件： - -- Markdown 源文件放置在你项目的 `docs` 目录； -- 使用的是默认的构建输出目录 (`.vuepress/dist`) ； -- 使用 [Yarn classic](https://classic.yarnpkg.com/zh-Hans/) 作为包管理器，当然也可以使用 NPM 。 -- VuePress 作为项目依赖安装，并在 `package.json` 中配置了如下脚本： - -```json -{ - "scripts": { - "docs:build": "vuepress build docs" - } -} -``` - -## GitHub Pages - -1. 设置正确的 [base](../reference/config.md#base) 选项。 - - 如果你准备发布到 `https://.github.io/` ，你可以省略这一步，因为 `base` 默认就是 `"/"` 。 - - 如果你准备发布到 `https://.github.io//` ，也就是说你的仓库地址是 `https://github.com//` ，则将 `base` 设置为 `"//"`。 - -2. 选项你想要使用的 CI 工具。这里我们以 [GitHub Actions](https://github.com/features/actions) 为例。 - - 创建 `.github/workflows/docs.yml` 文件来配置工作流。 - -::: details 点击展开配置样例 -```yaml -name: docs - -on: - # 每当 push 到 main 分支时触发部署 - push: - branches: [main] - # 手动触发部署 - workflow_dispatch: - -jobs: - docs: - runs-on: ubuntu-latest - - steps: - - uses: actions/checkout@v2 - with: - # “最近更新时间” 等 git 日志相关信息，需要拉取全部提交记录 - fetch-depth: 0 - - - name: Setup Node.js - uses: actions/setup-node@v1 - with: - # 选择要使用的 node 版本 - node-version: '14' - - # 缓存 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- - - # 如果缓存没有命中，安装依赖 - - name: Install dependencies - if: steps.yarn-cache.outputs.cache-hit != 'true' - run: yarn --frozen-lockfile - - # 运行构建脚本 - - name: Build VuePress site - run: yarn docs:build - - # 查看 workflow 的文档来获取更多信息 - # @see https://github.com/crazy-max/ghaction-github-pages - - name: Deploy to GitHub Pages - uses: crazy-max/ghaction-github-pages@v2 - with: - # 部署到 gh-pages 分支 - target_branch: gh-pages - # 部署目录为 VuePress 的默认输出目录 - build_dir: docs/.vuepress/dist -``` -::: - - -::: tip -请参考 [GitHub Pages 官方指南](https://pages.github.com/) 来获取更多信息。 -::: - -## GitLab Pages - -1. 设置正确的 [base](../reference/config.md#base) 选项。 - - 如果你准备发布到 `https://.gitlab.io/` ，你可以省略这一步，因此 `base` 默认就是 `"/"` 。 - - 如果你准备发布到 `https://.gitlab.io//` ，也就是说你的仓库地址是 `https://gitlab.com//` ，则将 `base` 设置为 `"//"`。 - -2. 创建 `.gitlab-ci.yml` 文件来配置 [GitLab CI](https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/) 工作流。 - -::: details 点击展开配置样例 -```yaml -# 选择你要使用的 docker 镜像 -image: node:14-buster - -pages: - # 每当 push 到 main 分支时触发部署 - only: - - main - - # 缓存 node_modules - cache: - paths: - - node_modules/ - - # 安装依赖并运行构建脚本 - script: - - yarn --frozen-lockfile - - yarn docs:build --dest public - - artifacts: - paths: - - public -``` -::: - -::: tip -请参考 [GitLab Pages 官方指南](https://docs.gitlab.com/ce/user/project/pages/#getting-started) 来获取更多信息。 -::: - -## Google Firebase - -1. 请确保你已经安装了 [firebase-tools](https://www.npmjs.com/package/firebase-tools)。 - -2. 在你项目的根目录下创建 `firebase.json` 和 `.firebaserc`，并包含以下内容： - -`firebase.json`: - -```json -{ - "hosting": { - "public": "./docs/.vuepress/dist", - "ignore": [] - } -} -``` - -`.firebaserc`: - -```json -{ - "projects": { - "default": "" - } -} -``` - -3. 在执行了 `yarn docs:build` 或 `npm run docs:build` 后, 使用 `firebase deploy` 指令来部署。 - -::: tip -请参考 [Firebase CLI 官方指南](https://firebase.google.com/docs/cli) 来获取更多信息。 -::: - -## Heroku - -1. 首先安装 [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli)； - -2. [在这里](https://signup.heroku.com) 注册一个 Heroku 账号； - -3. 运行 `heroku login` 并填写你的 Heroku 认证信息： - -```bash -heroku login -``` - -4. 在你的项目根目录中，创建一个名为 `static.json` 的文件，并包含下述内容： - -`static.json`: - -```json -{ - "root": "./docs/.vuepress/dist" -} -``` - -这里是你项目的配置，请参考 [heroku-buildpack-static](https://github.com/heroku/heroku-buildpack-static) 来获取更多信息。 - -## Netlify - -1. 前往 [Netlify](https://netlify.com) ，从 GitHub 创建一个新项目，并进行如下配置： - - - **Build Command:** `yarn docs:build` - - **Publish directory:** `docs/.vuepress/dist` - -2. 设置 [Environment variables](https://docs.netlify.com/configure-builds/environment-variables) 来选择 Node 版本： - - - `NODE_VERSION`: 14 - -3. 点击 deploy 按钮。 - -## Vercel - -请查看 [Creating and Deploying a VuePress App with Vercel](https://vercel.com/guides/deploying-vuepress-to-vercel). - - - -## 云开发 CloudBase - -[云开发 CloudBase](https://cloudbase.net/?site=vuepress) 是一个云原生一体化的 Serverless 云平台，支持静态网站、容器等多种托管能力，并提供简便的部署工具 [CloudBase Framework](https://cloudbase.net/framework.html?site=vuepress) 来一键部署应用。 - -1. 全局安装 CloudBase CLI ： - -```bash -npm install -g @cloudbase/cli -``` - -2. 在项目根目录运行以下命令一键部署 VuePress 应用，在部署之前可以先 [开通环境](https://console.cloud.tencent.com/tcb/env/index?tdl_anchor=ad&tdl_site=vuejs)： - -```bash -cloudbase init --without-template -cloudbase framework:deploy -``` - - CloudBase CLI 首先会跳转到控制台进行登录授权，然后将会交互式进行确认。 - - 确认信息后会立即进行部署，部署完成后，可以获得一个自动 SSL，CDN 加速的网站应用，你也可以搭配使用 GitHub Action 来持续部署 GitHub 上的 VuePress 应用。 - - 也可以使用 `cloudbase init --template vuepress` 快速创建和部署一个新的 VuePress 应用。 - -::: tip -更多详细信息请查看 CloudBase Framework 的[部署项目示例](https://github.com/TencentCloudBase/cloudbase-framework?site=vuepress#%E9%A1%B9%E7%9B%AE%E7%A4%BA%E4%BE%8B) -::: - -## 21 云盒子 - -请查看 [21 云盒子 - 部署一个 VuePress 静态网页](https://www.21yunbox.com/docs/#/deploy-vuepress)。 diff --git a/docs/zh/guide/faq.md b/docs/zh/guide/faq.md new file mode 100644 index 00000000..307d253c --- /dev/null +++ b/docs/zh/guide/faq.md @@ -0,0 +1 @@ +# 常见问题 \ No newline at end of file diff --git a/docs/zh/guide/i18n.md b/docs/zh/guide/i18n.md deleted file mode 100644 index 8ca254ea..00000000 --- a/docs/zh/guide/i18n.md +++ /dev/null @@ -1,70 +0,0 @@ -# 多语言支持 - -## 站点多语言配置 - -要启用 VuePress 的多语言支持，首先需要使用如下的文件目录结构： - -``` -docs -├─ README.md -├─ foo.md -├─ nested -│  └─ README.md -└─ zh - ├─ README.md - ├─ foo.md - └─ nested -    └─ README.md -``` - -然后，在你的 [配置文件](./configuration.md#配置文件) 中设置 `locales` 选项： - -```js -module.exports = { - locales: { - // 键名是该语言所属的子路径 - // 作为特例，默认语言可以使用 '/' 作为其路径。 - '/': { - lang: 'en-US', - title: 'VuePress', - description: 'Vue-powered Static Site Generator', - }, - '/zh/': { - lang: 'zh-CN', - title: 'VuePress', - description: 'Vue 驱动的静态网站生成器', - }, - }, -} -``` - -如果一个语言没有声明 `lang`, `title`, `description` 或者 `head` ，VuePress 将会尝试使用顶层配置的对应值。如果每个语言都声明了这些值，那么顶层配置中的对应值可以被省略。 - -::: tip -配置参考： [locales](../reference/config.md#locales) -::: - -## 主题多语言配置 - -VuePress 没有限制主题如何提供多语言支持，因此每个主题可能会有不同的多语言配置方式，而且部分主题可能不会提供多语言支持。建议你查看主题本身的文档来获取更详细的指引。 - -如果你使用的是默认主题，那么它提供多语言支持的方式和上述是一致的： - -```js -module.exports = { - themeConfig: { - locales: { - '/': { - selectLanguageName: 'English', - }, - '/zh/': { - selectLanguageName: '简体中文', - }, - }, - }, -} -``` - -::: tip -配置参考： [默认主题 > locales](../reference/default-theme/config.md#locales) -::: diff --git a/docs/zh/guide/markdown.md b/docs/zh/guide/markdown.md deleted file mode 100644 index f10ee89a..00000000 --- a/docs/zh/guide/markdown.md +++ /dev/null @@ -1,369 +0,0 @@ -# Markdown - -在阅读本章节之前，请确保你已经对 Markdown 有所了解。如果你还不了解 Markdown ，请先学习一些 [Markdown 教程](https://commonmark.org/help/)。 - -## 语法扩展 - -VuePress 会使用 [markdown-it](https://github.com/markdown-it/markdown-it) 来解析 Markdown 内容，因此可以借助于 markdown-it 插件来实现 [语法扩展](https://github.com/markdown-it/markdown-it#syntax-extensions) 。 - -本章节将会介绍 VuePress 内置支持的 Markdown 语法扩展。 - -你也可以通过 [markdown](../reference/config.md#markdown) 和 [extendsMarkdown](../reference/plugin-api.md#extendsmarkdown) 来配置这些内置扩展、加载更多 markdown-it 插件、实现你自己的扩展等。 - -### 内置 - -由 markdown-it 内置支持： - -- [表格](https://help.github.com/articles/organizing-information-with-tables/) (GFM) -- [删除线](https://help.github.com/articles/basic-writing-and-formatting-syntax/#styling-text) (GFM) - -### 标题锚点 - -你可能已经注意到，当你把鼠标放在各个章节的标题上时，会显示出一个 `#` 锚点。点击这个 `#` 锚点，可以直接跳转到对应章节。 - -::: tip -标题锚点扩展由 [markdown-it-anchor](https://github.com/valeriangalliat/markdown-it-anchor) 支持。 - -配置参考： [markdown.anchor](../reference/config.md#markdown-anchor) -::: - -### 链接 - -在你使用 Markdown 的 [链接语法](https://spec.commonmark.org/0.29/#link-reference-definitions) 时， VuePress 会为你进行一些转换。 - -以我们文档的源文件为例： - -```bash -└─ docs - └─ zh - ├─ guide - │ ├─ getting-started.md - │ ├─ markdown.md # <- 我们在这里 - │ └─ README.md - ├─ reference - │ └─ config.md - └─ README.md -``` - -**原始 Markdown** - -```md -[首页](/zh/README.md) -[指南](/zh/guide/) -[快速上手](./getting-started.md) -[markdown.links](../reference/config.md#links) -[GitHub](https://github.com) -``` - -**转换为** - -```vue -首页 -指南 -快速上手 -markdown.links -GitHub -``` - -**渲染为** - -[首页](/zh/README.md) -[指南](/zh/guide/) -[快速上手](./getting-started.md) -[markdown.links](../reference/config.md#links) -[GitHub](https://github.com) - -**解释** - -- 内部链接会被转换为 `` 以便进行 SPA 导航。 -- 指向 `.md` 文件的内部链接会被转换为目标页面的 [路由路径](./page.md#路由)，并且支持绝对路径和相对路径。 -- 外部链接会被添加 `target="_blank" rel="noopener noreferrer"` 属性和一个 标记。 - -::: tip -链接扩展是由我们的内置插件支持的。 - -配置参考： [markdown.links](../reference/config.md#markdown-links) - -参考: [內置组件 > OutboundLink](../reference/components.md#outboundlink) -::: - -### Emoji :tada: - -你可以在你的 Markdown 内容中输入 `:EMOJICODE:` 来添加 Emoji 表情。 - -前往 [emoji-cheat-sheet.com](https://emoji-cheat-sheet.com/) 来查看所有可用的 Emoji 表情和对应代码。 - -**输入** - -```md -VuePress 2 已经发布 :tada: ！ -``` - -**输出** - -VuePress 2 已经发布 :tada: ！ - -::: tip -Emoji 扩展由 [markdown-it-emoji](https://github.com/markdown-it/markdown-it-emoji) 支持。 - -配置参考： [markdown.emoji](../reference/config.md#markdown-emoji) -::: - -### 目录 - -如果你想要把当前页面的目录添加到 Markdown 内容中，你可以使用 `[[toc]]` 语法。 - -**输入** - -```md -[[toc]] -``` - -**输出** - -[[toc]] - -目录中的标题将会链接到对应的 [标题锚点](#标题锚点)，因此如果你禁用了标题锚点，可能会影响目录的功能。 - -::: tip -目录扩展是由我们的内置插件支持的，该扩展 Fork 并修改自 [markdown-it-toc-done-right](https://github.com/nagaozen/markdown-it-toc-done-right)。 - - -配置参考： [markdown.toc](../reference/config.md#markdown-toc) -::: - -### 代码块 - -下列代码块扩展是在 Node 端进行 Markdown 解析的时候实现的。这意味着代码块并不会在客户端被处理。 - -如果你想使用 [prism.js](https://prismjs.com/#basic-usage) 或 [highlight.js](https://highlightjs.org/) 在客户端进行语法高亮，你可以禁用我们的代码块扩展，然后手动在客户端引入你想要使用的库。 - -#### 语法高亮 - -VuePress 使用 [Prism](https://prismjs.com/) 来对代码块进行语法高亮。 - -Prism 支持多种编程语言，你可以前往 [Prism supported languages](https://prismjs.com/#supported-languages) 来查看所有可用的编程语言。 - -你只需要在代码块前添加对应语言的标识符，就可以启用代码高亮： - -**输入** - -````md -```ts -import type { UserConfig } from '@vuepress/cli' - -export const config: UserConfig = { - title: '你好， VuePress', -} -``` -```` - -**输出** - -```ts -import type { UserConfig } from '@vuepress/cli' - -export const config: UserConfig = { - title: '你好， VuePress', -} -``` - -::: tip -代码高亮扩展是由我们的内置插件支持的。 - -配置参考： [markdown.code.highlight](../reference/config.md#markdown-code-highlight) -::: - -#### 行高亮 - -你可以在代码块添加行数范围标记，来为对应代码行进行高亮： - -**输入** - -````md -```ts{1,6-8} -import type { UserConfig } from '@vuepress/cli' - -export const config: UserConfig = { - title: '你好， VuePress', - - themeConfig: { - logo: 'https://vuejs.org/images/logo.png', - }, -} -``` -```` - -**输出** - -```ts{1,6-8} -import type { UserConfig } from '@vuepress/cli' - -export const config: UserConfig = { - title: '你好， VuePress', - - themeConfig: { - logo: 'https://vuejs.org/images/logo.png', - }, -} -``` - -行数范围标记的例子： - -- 行数范围： `{5-8}` -- 多个单行： `{4,7,9}` -- 组合： `{4,7-13,16,23-27,40}` - -::: tip -行高亮扩展是由我们的内置插件支持的，该扩展 Fork 并修改自 [markdown-it-highlight-lines](https://github.com/egoist/markdown-it-highlight-lines)。 - -配置参考： [markdown.code.highlightLines](../reference/config.md#markdown-code-highlightlines) -::: - -#### 行号 - -你肯定已经注意到在代码块的最左侧会展示行号。这个功能是默认启用的，你可以通过配置来禁用它。 - -你可以在代码块添加 `:line-numbers` / `:no-line-numbers` 标记来覆盖配置项中的设置。 - -**输入** - -````md -```ts -// 行号默认是启用的 -const line2 = 'This is line 2' -const line3 = 'This is line 3' -``` - -```ts:no-line-numbers -// 行号被禁用 -const line2 = 'This is line 2' -const line3 = 'This is line 3' -``` -```` - -**输出** - -```ts -// 行号默认是启用的 -const line2 = 'This is line 2' -const line3 = 'This is line 3' -``` - -```ts:no-line-numbers -// 行号被禁用 -const line2 = 'This is line 2' -const line3 = 'This is line 3' -``` - -::: tip -行号扩展是由我们的内置插件支持的。 - -配置参考： [markdown.code.lineNumbers](../reference/config.md#markdown-code-linenumbers) -::: - -#### 添加 v-pre - -由于 [模板语法可以在 Markdown 中使用](#模板语法)，它也同样可以在代码块中生效。 - -为了避免你的代码块被 Vue 编译， VuePress 默认会在你的代码块添加 [v-pre](https://v3.vuejs.org/api/directives.html#v-pre) 指令。这一默认行为可以在配置中关闭。 - - -你可以在代码块添加 `:v-pre` / `:no-v-pre` 标记来覆盖配置项中的设置。 - -::: warning -模板语法的字符有可能会被语法高亮器解析，比如 "Mustache" 语法（即双花括号）。因此，就像下面的例子一样，在某些语言中 `:no-v-pre` 可能并不能生效。 - -如果你无论如何都想在这种语言中使用 Vue 语法，你可以尝试禁用默认的语法高亮，然后在客户端实现你的自定义代码高亮。 -::: - -**输入** - -````md -```md - -1 + 2 + 3 = {{ 1 + 2 + 3 }} -``` - -```md:no-v-pre - -1 + 2 + 3 = {{ 1 + 2 + 3 }} -``` - -```js:no-v-pre -// 由于 JS 代码高亮，这里不会被正确编译 -const onePlusTwoPlusThree = {{ 1 + 2 + 3 }} -``` -```` - -**输出** - -```md - -1 + 2 + 3 = {{ 1 + 2 + 3 }} -``` - -```md:no-v-pre - -1 + 2 + 3 = {{ 1 + 2 + 3 }} -``` - -```js:no-v-pre -// 由于 JS 代码高亮，这里不会被正确编译 -const onePlusTwoPlusThree = {{ 1 + 2 + 3 }} -``` - -::: tip -v-pre 扩展是由我们的内置插件支持的。 - -配置参考： [markdown.code.vPre](../reference/config.md#markdown-vpre) -::: - -## 在 Markdown 中使用 Vue - -这一章节会介绍 Vue 在 Markdown 中一些基本用法。 - -可以前往 [深入 > Markdown 和 Vue SFC](./advanced/markdown.md) 来了解更多内容。 - -### 模板语法 - -我们知道： - -- Markdown 中允许使用 HTML。 -- Vue 模板语法是和 HTML 兼容的。 - -这意味着， Markdown 中允许直接使用 [Vue 模板语法](https://v3.vuejs.org/guide/template-syntax.html)。 - -**输入** - -```md -一加一等于： {{ 1 + 1 }} - - span: {{ i }} -``` - -**输出** - -一加一等于： {{ 1 + 1 }} - - span: {{ i }} - -### 组件 - -你可以在 Markdown 中直接使用 Vue 组件。 - -**输入** - -```md -这是默认主题内置的 `` 组件 -``` - -**输出** - -这是默认主题内置的 `` 组件 - -::: tip -前往 [内置组件](../reference/components.md) 查看所有内置组件。 - -前往 [默认主题 > 内置组件](../reference/default-theme/components.md) 查看默认主题中的所有内置组件。 -::: diff --git a/docs/zh/guide/page.md b/docs/zh/guide/page.md deleted file mode 100644 index 13a019a4..00000000 --- a/docs/zh/guide/page.md +++ /dev/null @@ -1,55 +0,0 @@ -# 页面 - -VuePress 是以 Markdown 为中心的。你项目中的每一个 Markdown 文件都是一个单独的页面。 - -## 路由 - -默认情况下，页面的路由路径是根据你的 Markdown 文件的相对路径决定的。 - -假设这是你的 Markdown 文件所处的目录结构： - -``` -└─ docs - ├─ guide - │ ├─ getting-started.md - │ └─ README.md - ├─ contributing.md - └─ README.md -``` - -将 `docs` 目录作为你的 [sourceDir](../reference/cli.md) ，例如你在运行 `vuepress dev docs` 命令。此时，你的 Markdown 文件对应的路由路径为： - -| 相对路径 | 路由路径 | -|--------------------|----------------------| -| `/README.md` | `/` | -| `/contributing.md` | `/contributing.html` | -| `/guide/README.md` | `/guide/` | -| `/guide/page.md` | `/guide/page.html` | - -## Frontmatter - -Markdown 文件可以包含一个 [YAML](https://yaml.org/) Frontmatter 。Frontmatter 必须在 Markdown 文件的顶部，并且被包裹在一对三短划线中间。下面是一个基本的示例： - -```md ---- -lang: zh-CN -title: 页面的标题 -description: 页面的描述 ---- -``` - -你肯定注意到 Frontmatter 中的字段和[配置文件](./configuration.md#config-file)中的[站点配置](./configuration.md#站点配置)十分类似。你可以通过 Frontmatter 来覆盖当前页面的 `lang`, `title`, `description` 等属性。因此，你可以把 Frontmatter 当作页面级作用域的配置。 - -同样的，VuePress 有一些内置支持的 Frontmatter 字段，而你使用的主题也可能有它自己的特殊 Frontmatter 。 - -::: tip -前往 [Frontmatter 参考](../reference/config.md) 查看 VuePress 支持的 Frontmatter 配置。 - -前往 [默认主题 > Frontmatter 参考](../reference/default-theme/frontmatter.md) 查看默认主题的 Frontmatter 配置。 -::: - -## 内容 - -页面的主要内容是使用 Markdown 书写的。VuePress 首先会将 Markdown 转换为 HTML ，然后将 HTML 作为 Vue 单文件组件的 `