VuePress快速上手(默认主题)

曾经终败给现在 2022-11-14 10:11 660阅读 0赞

### 文章目录 ###

*  简要介绍
 *  安装vuePress
 *   *  步骤一：
     *  步骤二：
     *  步骤三：现有项目中使用 VuePress 管理文档，从此处开始
     *  步骤四：
     *  步骤五：
     *  步骤六：
 *  完善目录结构(满足基本需求)
 *  开启首页展示
 *  顶部导航栏
 *   *  LOGO
     *  顶部链接
 *  通过更改目录结构选择侧边栏样式
 *   *  一：展示全部 & 自动生成
     *  二：分页面展示
 *  Git 仓库和编辑链接
 *  页面滚动
 *  上 / 下一篇链接
 *  图片显示
 *  部署至GitHub Pages
 *   *  仓库准备
     *  打包项目
 *  说明/附录：
 *   *  说明
     *   *  适用范围：
     *  附录
     *   *   *  相关技术

# 简要介绍 #

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

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

详细介绍移步：[vuePress中文网 - 介绍][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`: 客户端应用的增强。

# 开启首页展示 #

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQ1NjcwMDQy_size_16_color_FFFFFF_t_70]

在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',
      }
    }

## 顶部链接 ##

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQ1NjcwMDQy_size_16_color_FFFFFF_t_70 1]

通过 `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`  
![在这里插入图片描述][20210328142503797.png]

通过在`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
                 '/': [
                     '',   /* / */
                 ]
            },

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQ1NjcwMDQy_size_16_color_FFFFFF_t_70 2]

# 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
      }
    }

# 图片显示 #

推荐：

<img :src="$withBase('/w7kj4RTfVC91OZTHAmzwxA.png')" alt="foo">

另一种(不推荐)：

![img](../.vuepress/public/h95BgnHg4MBnm_4mOtO4cQ.png)

# 部署至GitHub Pages #

## 仓库准备 ##

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

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQ1NjcwMDQy_size_16_color_FFFFFF_t_70 3]

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

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

至此，仓库配置完毕

## 打包项目 ##

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)>

# 说明/附录： #

## 说明 ##

### 适用范围： ###

本篇仅针对默认主题，eladmin官方文档使用的是其自己开发的主题，引入了一些插件。同时也有博客主题，可以自行学习。

## 附录 ##

#### 相关技术 ####

通过 阿里语雀 一键转换为 vuepress 文档的轮子，发布于 2019-02-09：[一键转换][Link 1]（未测试）

[vuePress_ -]: http://caibaojian.com/vuepress/guide/
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQ1NjcwMDQy_size_16_color_FFFFFF_t_70]: /images/20221022/49c76b5dc72c4e0894ce62987961d769.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQ1NjcwMDQy_size_16_color_FFFFFF_t_70 1]: /images/20221022/6c5d58c5ffce4055b5fbc7e25b138a1c.png
[20210328142503797.png]: /images/20221022/17de7b20484d41189643c4cf834d9c24.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQ1NjcwMDQy_size_16_color_FFFFFF_t_70 2]: /images/20221022/af8fa410eb6245299684ebab85c656ad.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQ1NjcwMDQy_size_16_color_FFFFFF_t_70 3]: /images/20221022/5cbcd2f19fb4406bb14f8aaeb7fb2759.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQ1NjcwMDQy_size_16_color_FFFFFF_t_70 4]: /images/20221022/8687bdf4f71f4867a6447f21f8f3be16.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQ1NjcwMDQy_size_16_color_FFFFFF_t_70 5]: /images/20221022/9181014c99cd40f59386e5c514bf1368.png
[Link 1]: https://zhuanlan.zhihu.com/p/56376695