首页Vue 3Vuepress

# 使用 Vue 3 + Element Plus 从头开始写一个数据库网站 - 07 - 添加 VuePress Theme Hope 作为内嵌文档

由于 PrismJS 尚不支持 Vue 的语法高亮，因此 Vue 代码块均先使用 HTML 的高亮

2024-09-23

VuePress 是一个基于 Vue.js 的静态网站生成器，专为构建技术文档和博客等内容设计。

VuePress Theme Hope 是一个基于 VuePress 的主题，提供了丰富的 Markdown 语法、组件支持、交互演示、幻灯片、搜索等功能。我们采用它来为网站构建一个美观的帮助文档。这里是官方使用指南。

# 初始化文档

要将 vuepress-theme-hope 作为文档构建器添加到现有项目中，我们在项目根目录 ADDB/ 中运行以下命令:

> pnpm create vuepress-theme-hope add docs
.../1934ccb97ae-7cbc                     |  +61 ++++++
.../1934ccb97ae-7cbc                     | Progress: resolved 61, reused 37, downloaded 24, added 61, done
✔ Select a language to display / 选择显示语言 English
✔ Choose package manager pnpm
✔ Which bundler do you want to use? vite
Updating package.json...
Generating tsconfig.json...
✔ What type of project do you want to create? docs
✔ Does the project need multiple languages? no
Generating Template...
✔ Initialize a git repository? no

这会在根目录 ADDB/ 目录下创建一个 docs/ 目录，结构如下

docs/
├── .vuepress/
├── demo/
├── guide/
├── portfolio.md
├── README.md

同时，该命令会修改根目录中的 package.json 文件，在 scripts 块中增加了这些内容：

"docs:build": "vuepress-vite build docs",
"docs:clean-dev": "vuepress-vite dev docs --clean-cache",
"docs:dev": "vuepress-vite dev docs",
"docs:update-package": "pnpm dlx vp-update"

这意味着我们可以在根目录中直接使用 pnpm docs:dev 来预览我们的文档页

我们先前已经在 ADDB/src/App.vue 组件中定义了整个数据库网站的 menu 和 footer

现在，我们希望在点击 About 菜单时能够访问这个文档

针对我们的需求，修改 ADDB/docs/.vuepress/config.ts 配置文件：

import { defineUserConfig } from "vuepress";
import { hopeTheme } from "vuepress-theme-hope";
// import theme from "./theme.js";
export default defineUserConfig({
    base: "/about/",
    lang: "en-US",
    // title: "Docs Demo",
    // description: "A docs demo for vuepress-theme-hope",
    theme: hopeTheme({
        navbar: false,
    }),
    // Enable it with pwa
    // shouldPrefetch: false,
    dest: "public/about",
});
主要的修改如下：


    

  • 设置了  base: "/about/" ，使生成的文档文件会基于  /about/  路径访问
    • 

  • 由于文档自带一个 menu，我们在配置文件中取消它
    • 

  • ADDB/public/  用于存放整个项目的静态资源，我们将文档构建的输出目录改为  ADDB/public/about/ ，与 base 一致
    • 



# 嵌入文档


最简单的方法是在页面用  iframe  嵌入生成的文档：


我们仍然可以在  ADDB/src/views/  中编写一个  AboutDocs.vue  文件来实现


但是在此处，我们来展示一下将其作为组件  ADDB/src/components/AboutDocs.vue  的写法：


<template>
    <iframe :src="docPath" class="docs-iframe"></iframe>
</template>
<script setup>
import { computed } from "vue";
import { useRoute } from "vue-router";
const route = useRoute();
// 动态计算文档路径
const docPath = computed(() => {
    const subPath = route.params.pathMatch || "";
    return `/about/${subPath}`;
});
</script>
<style scoped>
.docs-iframe {
    width: 100%;
    height: 100vh;
    border: none;
}
</style>
一点缺陷


我们将样式设置为无边框，且高度为视口高度，但这种方法仍然有一定的缺陷：


当文档页面高度超过了视口高度，iframe 也会出现滚动条，这在体验上是不太友好的


为了整体性与沉浸性，我尝试了数种方法来使 iframe 可以根据内部文档的高度自适应高度，但都没有成功，目前我没有办法解决这个问题。




我们在  ADDB/src/router/index.js  添加 About 页面的路由


import { createRouter, createWebHistory } from 'vue-router'
...
const router = createRouter({
    history: createWebHistory(import.meta.env.BASE_URL),
    routes: [
        ...
        {
            path: '/about',
            redirect: '/about/index.html', // 默认重定向到文档主页
        },
        {
            path: '/about/:pathMatch(.*)*',
            name: 'AboutDocs',
            component: () => import('@/components/AboutDocs.vue'),
        },
    ]
})
export default router
在以上配置中，我们明确地将  /about  重定向到文档首页  /about/index.html ，并使用  pathMatch  捕获  /about/  下的子路径


# 参考资料