vuepress搭建网站原创

# 一. 使用本项目

# 1. 克隆到本地

git clone https://github.com/liyao52033/vuepress-default.git

yarn install

1
2
3

# 2. 脚本说明

"scripts": {
    "docs:dev": "vuepress dev docs",  //启动项目
    "docs:build": "vuepress build docs", // 打包项目
    "docs:nav": "vuepress nav docs -f" , // 生成导航栏与侧边栏
    "deploy": "./docs/.vuepress/deploy.sh", //部署到github.io
    "push": "./docs/push.sh"  //推送到github
  },

1
2
3
4
5
6
7

# 3. 启动项目

yarn run docs:dev

# 4. 在docs构建目录如下

docs
├─ README.md
├─ contact.md
├─ about.md
├─ foo/
│  ├─ test
│  ├─  ├─ README.md   
│  ├─ README.md
│  ├─ one.md
│  └─ two.md
└─ bar/
   ├─ README.md
   ├─ three.md
   └─ four.md

1
2
3
4
5
6
7
8
9
10
11
12
13
14

文件夹可以嵌套，但每个文件夹都必须有README目录，不然会报404

# 5. 导航栏与侧边栏

voding主题已经提供结构化侧边栏 (opens new window)，也内置了自动生成侧边栏插件，两者选一即可

若使用自动生成侧边栏插件，执行以下命令，将生成的nav.js在.vuppress/config.js引入即可自动生成侧边栏, 更多内容见官网 (opens new window)

// 生成nav.js
yarn run docs:nav

//使用插件并引入nav.js  .vuepress/config.js
const nav = require("./nav.js");
module.exports = {
  plugins: [
     ["vuepress-plugin-auto-sidebar",{
   sidebarDepth: 2,
     collapse: {
       open: true,
    },
}],
  ]
  themeConfig: {
    nav
}
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

若使用vdoing主题侧边栏，导航栏只需写与.vuepress同层的一级目录，link写该文件夹内任意md文件frontmatter的permalink,格式如下，更多内容见官网 (opens new window)

 // config.js
module.exports = {
    themeConfig: {
        nav:  [
            // 没有二级导航时可以直接添加
           {text: '目录页', link: '/web/'},

          // 有二级导航时
           {text: '页面',
            /** 目录页， vdoing主题新增的配置项，有二级导航时，可以点击一级导航跳到目录页，
             依赖于结构化的侧边栏数据，就是说你需要在config.js配置 sidebar: 'structuring' 或 sidebar: { mode: 'structuring', collapsable: false} 才能实现目录页数据的获取。**/
               link: '/ui/',   
               items: [
                 {text: 'HTML', link: '/pages/11/'},
                 {text: 'CSS', link: '/pages/22/'},
               ]
            },
       ]
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# 6.部署，此处只部署到 USERNAME.github.io,其他情况见官网 (opens new window)

修改deploy.sh的仓库路径

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

1
2

部署

yarn run deploy

# 二. 从零到一根据官网搭建 (opens new window)

# 安装

yarn add -D vuepress

注意

如果你的现有项目依赖了 webpack 3.x，我们推荐使用 Yarn (opens new window) (opens new window)而不是 npm 来安装 VuePress。因为在这种情形下，npm 会生成错误的依赖树,导致项目无法启动

# 在 `package.json` 中添加脚本

这一步骤是可选的，但我们推荐你完成它。在下文中，我们会默认这些 scripts 已经被添加。

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

1
2
3
4
5
6

# 在本地启动服务器

yarn docs:dev

# 三. 目录结构

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

注意

请留意目录名的大写。

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 目录作为 targetDir （参考命令行接口 (opens new window)），下面所有的“文件的相对路径”都是相对于 docs 目录的。在项目根目录下的 package.json 中添加 scripts ：
```
{
  "scripts": {
    "dev": "vuepress dev docs",
    "build": "vuepress build docs"
  }
}
```
1
2
3
4
5
6
对于上述的目录结构，默认页面路由地址如下：

文件的相对路径页面路由地址

/README.md /

/guide/README.md /guide/

/config.md /config.html

文件的相对路径	页面路由地址
`/README.md`	`/`
`/guide/README.md`	`/guide/`
`/config.md`	`/config.html`

默认的主题提供了一个首页（Homepage）的布局 (用于这个网站的主页)。想要使用它，需要在你的根级 README.md 的 YAML front matter 指定 home: true。

# 导航栏与侧边栏配置

用Vuepress Plugin Auto Sidebar (opens new window)自动生成插件，详细文档 (opens new window)

# 安装

yarn add vuepress-plugin-auto-sidebar -D

# 使用 (opens new window)

Attention, do not put plugins in the themeConfig

module.exports = {
  plugins: [
    ["vuepress-plugin-auto-sidebar", {
       sidebarDepth: 2,
       collapse: {
          open: true,
      },
    }]
  ]
}

1
2
3
4
5
6
7
8
9
10

# 快速生成简单的导航栏

添加脚本到 package.json 中

{
  "scripts": {
    "docs:nav": "vuepress nav docs"
  }
}

1
2
3
4
5

执行命令
```
yarn run docs:nav
```
1

它将会在 .vuepress 文件夹下生成 nav.js 文件，每次新增文件夹都要执行一次该命令重新生成路由

引入生成的 nav 文件

const nav = require("./nav.js");

module.exports = {
  plugins: {
    "vuepress-plugin-auto-sidebar": {}
  },
  themeConfig: {
    nav
  }
}

1
2
3
4
5
6
7
8
9
10

# 专注写作

在docs目录下存放写的文章即可，目录如下

docs
├─ README.md
├─ contact.md
├─ about.md
├─ foo/
│  ├─ README.md
│  ├─ one.md
│  └─ two.md
└─ bar/
   ├─ README.md
   ├─ three.md
   └─ four.md

1
2
3
4
5
6
7
8
9
10
11
12

警告

每个文件夹下必须有一个README.md，不然跳转404

参考文章

Young Kbt blo (opens new window)

二丫讲梵 (opens new window)

Evan's blog (opens new window)

Suya's blog (opens new window)

#开源项目 #vuepress

上次更新: 2025/02/18 14:46:10

引入第三方组件库→

vuepress搭建网站原创

# 一. 使用本项目

# 1. 克隆到本地

# 2. 脚本说明

# 3. 启动项目

# 4. 在docs构建目录如下

# 5. 导航栏与侧边栏

# 6.部署，此处只部署到 USERNAME.github.io,其他情况见官网 (opens new window)

# 二. 从零到一根据官网搭建 (opens new window)

# 安装

# 在 package.json 中添加脚本

# 在本地启动服务器

# 三. 目录结构

# 默认的页面路由

# 导航栏与侧边栏配置

# 安装

# 使用 (opens new window)

# 快速生成简单的导航栏

# 专注写作

# 在 `package.json` 中添加脚本