最简化VuePress项目实践

在下面的例子,将从零开始,实现发布到互联网的文档项目,点此查看网络实例

安装VuePress

全局安装VuePress工具:

yarn global add vuepress@next

上述命令需要用户已经安装了nodeyarngit环境。如果用户对这一部分内容不熟悉,请参考相关教程

初始化VuePress项目

建立项目文件夹及首页

如在桌面上建立vuepress目录:

cd ~/desktop
mkdir vuepress
cd vuepress
yarn init
mkdir docs
cd docs
touch README.md
touch .vuepress/config.js

将形成如下目录结构及文件:

.
├─ docs
│  ├─ README.md
│  └─ .vuepress
│     └─ config.js
└─ package.json

docs目录中的README.md文件将成为项目的根目录文件,该文件会被渲染成为index.html

为项目添加内容

使用编辑器,为README.md文件添加、编辑内容,如:

# Hello
<!-- balabala -->

预览项目

vuepress dev docs

编译成功后,打开命令行中显示的本地预览地址,一般情况下为:

http://localhost:8080/

就能看到VuePress生成的页面。该页面是动态生成的,因此,我们想要发布到远程托管站点的话,需要生成静态网站,下面我们做一些必要的设置。

配置信息

发布网站时,首先需要在项目配置文件config.js(该文件在docs/.vuepess/)中设置网站主路径。例如:

module.exports = {
    title: 'VuePress学习笔记',
    description: 'VuePressV1.X学习笔记',
    base: "/vuepress/"
}

上面的设置,将和https://username.gitee.io/vuepress对应,使用gitee.com的pages服务即可将内容发布网络。

生成静态网站

vuepress build docs

使用git发布项目到远端托管站点

建立远端仓库

gitee.com中新建一个vuepress的项目,设置为公开。

建立本地仓库并推送到远程

git init
git add .
git commit -m "初始化"
git remote add origin https://gitee.com/username/vuepress.git
git push origin master

推动到远程仓库后,开启gitee.com提供的pages服务,设定合适的目录,如docs/.vuepress/dist,至此完成了从创建到发布的全部流程。

开启pages服务

接下来,我们不断完善项目内容。内容的显示,在VuePress中属于主题,目前,用户有三种选择:

  1. 使用默认主题。
  2. 使用社区主题。
  3. 自定义主题。

我们先从默认主题上手。

参考资料

  1. 官方文档
  2. 官方示例