VuePress快速上手(默认主题)

最新推荐文章于 2025-04-20 19:15:16 发布

原创最新推荐文章于 2025-04-20 19:15:16 发布

· 2.9k 阅读

10 ·

版权

文章标签：

#vue.js #vue #github #html #markdown

md转html 专栏收录该内容

1 篇文章

订阅专栏

VuePress 是一个将 Markdown 转换为静态网站的工具，适合创建技术文档。本文档详细介绍了从安装到部署的步骤，包括设置首页、导航栏、侧边栏样式、Git 仓库链接等。特别强调了在现有项目中使用 VuePress 的方法和注意事项，如目录结构的优化和版本一致性。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

简要介绍

VuePress是一个能够将我们编写的markdown文件转换为html文件的一个技术，通过一定规则的限制，并配合 githubpages 可以方便的将我们的多个或一个markdown文件转换为网页并部署在服务器上，供其自由跳转，并添加一些额外的链接。

同github相连接，在浏览网页的同时，我们可以设置允许其对github上的文件进行修改申请。

详细介绍移步：vuePress中文网 - 介绍

安装vuePress

仅介绍默认主题，现有项目中使用 VuePress 管理文档，从步骤 3 开始。

步骤一：

创建并进入一个新目录

mkdir vuepress-starter && cd vuepress-starter

步骤二：

使用你喜欢的包管理器进行初始化

yarn init # npm init

步骤三：现有项目中使用 VuePress 管理文档，从此处开始

将 VuePress 安装为本地依赖（现有项目中使用 VuePress 管理文档从这里开始）

我们已经不再推荐全局安装 VuePress

yarn add -D vuepress # npm install -D vuepress

TIPS

若项目中依赖了webpack3.x，推荐使用yarn而不是npm来安装VuePress，npm会产生错的依赖树。

步骤四：

创建文档

mkdir docs && echo '# Hello VuePress' > docs/README.md

步骤五：

在 package.json 中添加一些 scripts代码

这一步骤是可选的，推荐完成。下文中默认这些 scripts 已经被添加。

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

在现有项目中要确保vue版本与vuepress版本一致。

可在package.json中更改版本号，通过 cnpm install 或者 npm install 来更换版本，推荐cnpm。也可自行百度。

步骤六：

在本地启动服务器

yarn docs:dev # npm run docs:dev

至此，项目可以在本地运行。

完善目录结构(满足基本需求)

.
├── docs
│   ├── .vuepress
│   │   ├── public
│   │   ├── styles
│   │   │   └── palette.styl
│   │   └── config.js
│   │
│   ├── README.md
│   ├── guide
│   │   └── README.md
│   └── config.md
│ 
└── package.json

VuePress 遵循 “约定优于配置” 的原则，推荐的目录结构如下：
// 完整目录结构
.
├── docs
│   ├── .vuepress (可选的)
│   │   ├── components (可选的)
│   │   ├── theme (可选的)
│   │   │   └── Layout.vue
│   │   ├── public (可选的)
│   │   ├── styles (可选的)
│   │   │   ├── index.styl
│   │   │   └── palette.styl
│   │   ├── templates (可选的, 谨慎配置)
│   │   │   ├── dev.html
│   │   │   └── ssr.html
│   │   ├── config.js (可选的)
│   │   └── enhanceApp.js (可选的)
│   │ 
│   ├── README.md
│   ├── guide
│   │   └── README.md
│   └── config.md
│ 
└── package.json
注意

请留意目录名的大写。

docs/.vuepress: 用于存放全局的配置、组件、静态资源等。
docs/.vuepress/components: 该目录中的 Vue 组件将会被自动注册为全局组件。
docs/.vuepress/theme: 用于存放本地主题。
docs/.vuepress/styles: 用于存放样式相关的文件。
docs/.vuepress/styles/index.styl: 将会被自动应用的全局样式文件，会生成在最终的 CSS 文件结尾，具有比默认样式更高的优先级。
docs/.vuepress/styles/palette.styl: 用于重写默认颜色常量，或者设置新的 stylus 颜色常量。
docs/.vuepress/public: 静态资源目录。
docs/.vuepress/templates: 存储 HTML 模板文件。
docs/.vuepress/templates/dev.html: 用于开发环境的 HTML 模板文件。
docs/.vuepress/templates/ssr.html: 构建时基于 Vue SSR 的 HTML 模板文件。
docs/.vuepress/config.js: 配置文件的入口文件，也可以是 YML 或 toml。
docs/.vuepress/enhanceApp.js: 客户端应用的增强。

开启首页展示

在这里插入图片描述

在docs目录(根目录)下的README.md文件写下

---
home: true
heroImage: /img/hero.png # 此处需注意文件路径，public下的文件会被复制到生成目录的根目录。img需自行判断是否添加
heroText: Hero 标题
tagline: Hero 副标题
actionText: 快速上手 →
actionLink: /guide/	 # 此处的guide指的是跳转到对应文件夹，默认加载其内的README.md文件，可以理解为index入口
features:
- title: 简洁至上
  details: 以 Markdown 为中心的项目结构，以最少的配置帮助你专注于写作。
- title: Vue驱动
  details: 享受 Vue + webpack 的开发体验，在 Markdown 中使用 Vue 组件，同时可以使用 Vue 来开发自定义主题。
- title: 高性能
  details: VuePress 为每个页面预渲染生成静态的 HTML，同时在页面被加载的时候，将作为 SPA 运行。
footer: MIT Licensed | Copyright © 2018-present Evan You
---

该内容之后的任意其他内容，将被解析为正常 markdown，并在特性部分之后渲染。

顶部导航栏

LOGO

在config.js文件内添加

// .vuepress/config.js
module.exports = {
  themeConfig: {
    logo: '/assets/img/logo.png',
  }
}

顶部链接

在这里插入图片描述

通过 themeConfig.nav 增加一些导航栏链接

// .vuepress/config.js
module.exports = {
themeConfig: {
    // 导航栏配置
    navbar: true // 开启导航
nav: [ 
    	// 普通链接
        { text: '常见问题', link: '/阿萨德/' },
        { text: '更新日志', link: '/是/' },
        { text: '捐赠支持', link: '/啊发顺丰/' },
    	// 下拉列表
        { text: '体验地址', link: '/algorithm/',items: [
          { text: 'Chinese', link: '/language/chinese/' },
          { text: 'Japanese', link: '/language/japanese/' }
        ]},
    	// 分组下拉列表
        {
            text: 'GitHub', link: 'https://baidu.com', items: [
                { text: 'Group1', items: ["ASD/*ssss  */"] },
                { text: 'Group2', items: ["/* ssss */"] }
            ]
        },
	],
}
}

通过更改目录结构选择侧边栏样式

一：展示全部 & 自动生成

// .vuepress/config.js
module.exports = {
  themeConfig: {
    sidebar: 'auto', // 自动生成侧边栏
    sidebarDepth: 2, // 侧边栏显示2级
  }
}

0：禁用标题链接
1：提取到 h2 级别的标题。
2：提取 h2 和 h3 级别的标题

单页面实现：

在markDown文件顶部加入
---
sidebar: auto # 该页自动生成目录
sidebarDepth: 2 # 侧边栏显示2级
---

二：分页面展示

在guide里面建立多个md文件。入口文件命名为READEME.md
在这里插入图片描述

通过在config.js文件内使用分组导航实现vuepress官网效果。

sidebar: {
            '/guide/': [
                {
                    title: '介绍',   		 // 必要的 GROUP1
                    path: '/guide/',      // 可选的, 标题的跳转链接，应为绝对路径且必须存在
                    collapsable: false,   // 可选的, 默认值是 true,
                    sidebarDepth: 2,      // 可选的, 默认值是 1
                    children: [
                        ['', '快速了解'],      	/* /guide/ */
                        ['fastIn', '快速入门'], /* /guide/fastIn.html */
                        ['projectIntroduce', '项目介绍'],
                        ['frontHandbook', '前端手册'],
                        ['behindHandbook', '后端手册'],
                    ],
                    initialOpenGroupIndex: 0
                },
                {
                    title: '鸣谢',		   // 必要的 GROUP2
                    path: '/guide/',      	// 可选的, 标题的跳转链接，应为绝对路径且必须存在
                    collapsable: false, 	// 可选的, 默认值是 true,
                    sidebarDepth: 2,    	// 可选的, 默认值是 1
                    children: [
                        ['thanks', '特别鸣谢'],      /* /guide/thanks */
                        
                    ],
                    initialOpenGroupIndex: 0
                }
                
            ],

            // fallback
             '/': [
                 '',   /* / */
             ]
        },

在这里插入图片描述

Git 仓库和编辑链接

提供themeConfig.repo 选项，将会自动在每个页面的导航栏生成生成一个 GitHub 链接，以及在页面的底部生成一个 "Edit this page" 链接。

需要注意的是，当我们使用此功能时，默认打开的页面为.md文件，但gh-pages上部署的是打包后解析为.html的文件。所以我们需要在另一个分支上上传自己的打包前文件(页面后缀为.md)。

也就是说，我们的仓库里需要有两个分支，一个存放编译后的页面，一个存放编译前的文件。当我们通过该链接点击时，更改的是编译前的文件。(当然我们也可以分别建立两个仓库来解决这个问题)

// .vuepress/config.js
module.exports = {
  themeConfig: {
    // 假定是 GitHub. 同时也可以是一个完整的 GitLab URL
    // repo: 'vuejs/vuepress',
    // 自定义仓库链接文字。默认从 `themeConfig.repo` 中自动推断为
    // "GitHub"/"GitLab"/"Bitbucket" 其中之一，或是 "Source"。
    // repoLabel: '查看源码',
      
    // 以下为可选的编辑链接选项
    // 假如你的文档仓库和项目本身不在一个仓库：
    docsRepo: '<user>/<repo>',
    // 假如文档不是放在仓库的根目录下：
    docsDir: 'docs',
    // 假如文档放在一个特定的分支下：(主分支名要分清楚，是main还是master，默认是master，如果是main的话需要写出来)
    docsBranch: 'main',
    // 默认是 false, 设置为 true 来启用
    editLinks: true,
    // 默认为 "Edit this page"
    editLinkText: '帮助我们改善此页面！'
  }
}

YAML front matter 来禁用指定页面的编辑链接(写在页面头部即可)：

---
editLink: false
---

页面滚动

// .vuepress/config.js
module.exports = {
  themeConfig: {
    smoothScroll: true
  }
}

上 / 下一篇链接

其顺序和sidebar书写的顺序一致。

// .vuepress/config.js
module.exports = {
  themeConfig: {
    // 默认值是 true 。设置为 false 来禁用所有页面的 下一篇 链接
    nextLinks: false,
    // 默认值是 true 。设置为 false 来禁用所有页面的 上一篇 链接
    prevLinks: false
  }
}

图片显示

部署至GitHub Pages

仓库准备

首先，建立一个git仓库此处起名为VuePressTest

在这里插入图片描述

其次，去Settings选择Source，进行如下配置

在这里插入图片描述
注意，这里的branch要选则打包后上传的分支

至此，仓库配置完毕

打包项目

yarn run docs:build或者是npm run docs:build

根据用什么安装或者webpack版本来决定用哪一个，3.x的使用yarn打包

# 生成静态文件
npm run docs:build || yarn docs:build

# 进入生成的文件夹
cd docs/.vuepress/dist

# 如果是发布到自定义域名
# echo 'www.example.com' > CNAME

git init
git add -A
git commit -m 'deploy'

# 如果发布到 https://<USERNAME>.github.io
# git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git master

# 如果发布到 https://<USERNAME>.github.io/<REPO>
# git push -f git@github.com:<USERNAME>/<REPO>.git master:<分支名(如果使用主分支要分清用的那个名字，是main还是master)>