跳至主要內容

VuePress-v1

唐皓晨大约 8 分钟前端学习笔记VueVuePressMarkdown

VuePress-v1

项目搭建

1. 创建并进入新目录

mkdir vue-press-demo && cd vue-press-demo

2. 初始化

npm init -y

3. 安装 VuePress

npm install -D vuepress

4. 配置启动/打包脚本

在 package.json 添加一些 script

{
  "scripts": {
    "dev": "vuepress dev docs",
    "bulid": "vuepress build docs"
  }
}

目录结构

.
├── docs
│   ├── .vuepress (存放全局的配置、组件、静态资源等)
│   │   ├── components (目录中的 Vue 组件将会被自动注册为全局组件)
│   │   ├── theme (存放本地主题)
│   │   ├── public (存放本地资源)
│   │   ├── styles (存放样式相关的文件)
│   │   ├── templates (存储 HTML 模板文件)
│   │   ├── config.js (配置文件)
│   │   └── enhanceApp.js (客户端应用的增强)
│   │
│   ├── README.md（默认首页）
│   └── ... （页面）
│       └── README.md
│
└── package.json

基本配置

1. 常用配置项

module.exports = {
  base: '/', // 部署站点的基础路径
  locales: {
    // 多语言配置
    '/': {
      // 默认
      lang: 'zh-CN', // 语言标识
      title: "tang's blog", // 网站的标题
      description: '唐皓晨的个人博客', // 网站的描述
    },
  },
  title: 'Hello VuePress', // 网站的标题
  description: 'Just playing around', // 网站的描述
  head: [['link', { rel: 'icon', href: '/favicon.ico' }]], // 注入HTML <head> 标签中
  host: '0.0.0.0', // 开发环境主机名
  port: 8080, // 开发环境端口
  temp: '/path/to/@vuepress/core/.temp', // 客户端文件临时目录
  dest: '.vuepress/dist', // 打包输出目录
  locales: {}, // 多语言配置
  shouldPrefetch: () => true, // https://ssr.vuejs.org/zh/api/#shouldprefetch
  cache: true, // 可以用于指定 cache 的路径，同时也可以通过设置为 false 来在每次构建之前删除 cache
  extraWatchFiles: [], // 指定额外的需要被监听的文件（触发 vuepress 重新构建）
  theme: '', // 自定义主题
  themeConfig: {
    // 主题配置
    logo: '', // 导航栏图标
    nav: '', // 导航栏链接
    navbar: false, // 禁用导航栏
    sidebar: 'auto', // 侧边栏
    sidebarDepth: 2, // 嵌套标题链接深度
    displayAllHeaders: false, // 显示所有标题链接
  },
  plugins: {}, // 插件
  markdown: {
    lineNumbers: true, // 是否在每个代码块的左侧显示行号
    plugins: {}, // markdown 插件
    extractHeaders: ['h2', 'h3'], // 提取出的标题级别
  },
};

2. TypeScript 配置

使用 TypeScript 作为配置，将 .vuepress 下的 config.js 替换为 config.ts

import { defineConfig } from 'vuepress/config';
export default defineConfig({
  base: '/', // 部署站点的基础路径
  locales: {
    // 多语言配置
    '/': {
      // 默认
      lang: 'zh-CN', // 语言标识
      title: "tang's blog", // 网站的标题
      description: '唐皓晨的个人博客', // 网站的描述
    },
  },
  title: 'Hello VuePress', // 网站的标题
  description: 'Just playing around', // 网站的描述
  head: [['link', { rel: 'icon', href: '/favicon.ico' }]], // 注入HTML <head> 标签中
  host: '0.0.0.0', // 开发环境主机名
  port: 8080, // 开发环境端口
  temp: '/path/to/@vuepress/core/.temp', // 客户端文件临时目录
  dest: '.vuepress/dist', // 打包输出目录
  locales: {}, // 多语言配置
  shouldPrefetch: () => true, // https://ssr.vuejs.org/zh/api/#shouldprefetch
  cache: true, // 可以用于指定 cache 的路径，同时也可以通过设置为 false 来在每次构建之前删除 cache
  extraWatchFiles: [], // 指定额外的需要被监听的文件（触发 vuepress 重新构建）
  theme: '', // 自定义主题
  themeConfig: {
    // 主题配置
    logo: '', // 导航栏图标
    nav: '', // 导航栏链接
    navbar: false, // 禁用导航栏
    sidebar: 'auto', // 侧边栏
    sidebarDepth: 2, // 嵌套标题链接深度
    displayAllHeaders: false, // 显示所有标题链接
  },
  plugins: {}, // 插件
  markdown: {
    lineNumbers: true, // 是否在每个代码块的左侧显示行号
    plugins: {}, // markdown 插件
    extractHeaders: ['h2', 'h3'], // 提取出的标题级别
  },
});

vdoing 主题

使用 vuepress-theme-vdoing 搭建

1. 安装主题包

npm install vuepress-theme-vdoing -D

2. 使用主题

import { defineConfig4CustomTheme } from 'vuepress/config';
import { VdoingThemeConfig } from 'vuepress-theme-vdoing/types';
export default defineConfig4CustomTheme<VdoingThemeConfig>({
  // 可以使用原生配置项
  theme: 'vdoing',
  // 以下为 vdoing 主题配置，可参考 https://doc.xugaoyi.com/pages/a20ce8/
  category: false, // 是否打开分类功能，默认true
  tag: false, // 是否打开标签功能，默认true
  archive: false, // 是否打开归档功能，默认true
  categoryText: '随笔', // 碎片化文章（_posts文件夹的文章）预设生成的分类值，默认'随笔'
  updateBar: {
    // 最近更新栏
    showToArticle: false, // 显示到文章页底部，默认true
    moreArticle: '/archives', // “更多文章”跳转的页面，默认'/archives'
  },
  rightMenuBar: false, // 是否显示右侧文章大纲栏，默认true (屏宽小于1300px下无论如何都不显示)
  sidebarOpen: false, // 初始状态是否打开左侧边栏，默认true
  pageButton: false, // 是否显示快捷翻页按钮，默认true

  // 侧边栏  'structuring' | { mode: 'structuring', collapsable: Boolean} | 'auto' | <自定义>
  // 温馨提示：目录页数据依赖于结构化的侧边栏数据，如果你不设置为'structuring',将无法使用目录页
  sidebar: 'structuring',

  // 文章默认的作者信息，(可在md文件中单独配置此信息) string | {name: string, link?: string}
  author: {
    name: '', // 必需
    link: '', // 可选的
  },

  // 博主信息 (显示在首页侧边栏)
  blogger: {
    avatar: '', // 头像
    name: '', // 名字
    slogan: '前端界的小学生',
  },

  // 社交图标 (显示于博主信息栏和页脚栏。内置图标：https://doc.xugaoyi.com/pages/a20ce8/#social)
  social: {
    // 可选，阿里图标库在线css文件地址，对于主题没有的图标可自己添加。阿里图片库：https://www.iconfont.cn/
    iconfontCssFile: '//at.alicdn.com/t/xxx.css',
  },

  // 页脚信息
  footer: {
    createYear: 2022, // 博客创建年份
    copyrightInfo: '', // 博客版权信息，支持a标签或换行标签</br>
  },
});

常用插件

one-click-copy

代码块复制

  1. 安装
npm install vuepress-plugin-one-click-copy -D
  1. 配置插件
module.exports = {
  plugins: {
    'one-click-copy': {
      copySelector: [
        'div[class*="language-"] pre',
        'div[class*="aside-code"] aside',
      ], // 需要显示复制按钮的元素
      copyMessage: '复制成功', // 复制成功提示文字
      toolTipMessage: '复制代码', // 复制按钮title
      duration: 1000, // 复制成功提示文字显示时间
    },
  },
};

demo-block

demo 展示

  1. 安装
npm install vuepress-plugin-demo-block -D
  1. 配置插件
module.exports = {
  plugins: {
    'demo-block': {
      settings: {
        jsfiddle: false, // 是否显示 jsfiddle 链接
        codepen: true, // 是否显示 codepen 链接
        horizontal: false, // 是否展示为横向样式
      },
    },
  },
};

demo-container

demo 展示

  1. 安装
npm i vuepress-plugin-demo-container --save-dev
  1. 配置插件
module.exports = {
  plugins: {
    'demo-container': {
      component: 'demo-block', // 包裹代码与示例的组件名称。
      locales: [
        // 多语言配置
        {
          lang: 'zh-CN', // 语音标志
          'demo-block': {
            'show-text': '显示代码', // 展开代码按钮文字
            'hide-text': '隐藏代码', // 隐藏代码按钮文字
            'copy-text': '复制代码', // 复制代码按钮文字
            'copy-success': '复制成功', // 复制成功按钮文字
          },
        },
      ],
    },
  },
};

集成 element-ui

1. 安装 element-ui

npm install element-ui -S

2. 引入组件库

接下来需要修改用于客户端应用增强的 docs/.vuepress/enhanceApp.js 文件

/**
 * 扩展 VuePress 应用
 */
// 引入 element-ui
import Element from 'element-ui';
import 'element-ui/lib/theme-chalk/index.css';
export default ({
  Vue, // VuePress 正在使用的 Vue 构造函数
  options, // 附加到根实例的一些选项
  router, // 当前应用的路由实例
  siteData, // 站点元数据
}) => {
  Vue.use(Element);
};

3. 正常使用

<template>
  <div>
    <el-button @click="click">click</el-button>
  </div>
</template>
<script>
export default {
  methods: {
    click() {
      this.$message.info('按钮点击了');
    },
  },
};
</script>

4. 问题及解决方案

1. 安装后启动报错

按以上步骤安装并启动项目后，报了以下错误

控制台报错
控制台报错

在浏览器打开白屏，且控制台报错

浏览器报错
浏览器报错

根据控制台报错安装缺失依赖

npm install async-validator@1.11.5

安装依赖，并重启项目后，页面显示正常，并且可以使用 element-ui 中的组件

默认页脚
Copyright © 2025 唐皓晨