关于开箱即用的文档静态网站生成器VuePress

关于VuePress

一个由Vue驱动的静态文档网站生成框架,具有开箱即用的优点。

给项目添加.gitignore

.gitignore是git用来排除目录的清单,我们把以下目录加入其中,以便每次操作都把这些东西带上,搞得git项目乱七八糟的。

# 项目依赖包
node_modules 

# Build之后的输出目录
.vuepress/dist

安装VuePress

全局安装VuePress

npm install -g vuepress

或者

yarn global add vuepress

在现有项目文件夹安装

npm install -D vuepress

或者

yarn add -D vuepress

给现有项目添加VuePress支持

在项目文件夹执行如下命令即可。

vuepress dev .

顺利的话,它就安装以来的Node包,然后启动一个8080的http监听。

打开网址(http://localhost:8080)[http://localhost:8080]访问

如果提示你,没有权限执行ps命令,那就右键管理员打开PowerShell,然后执行以下命令解锁:

set-executionpolicy remotesigned

升级VuePress

npm i @vuepress/core

生产静态网站

vuepress build .

配置运行

根目录新建package.json文件,内容

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

这样就可以在终端界面运行:

开始写作

npm run dev

生成静态文件

npm run build

默认静态文件会生成在项目目录的.vuepress/dist

配置静态

看是否存在.vuepress/config.js文件,没有的话就新建一个。

module.exports = {
    title: `XXXXXXX- Home`,
    description: `XXXXXXX`
}

静态资源

静态资源文件夹

关于静态资源应该放哪,有个默认可选路径.vuepress/public,如果这个文件夹没有,你就自己新建一个,默认这个会打包到静态根目录。
我们在这个public底下,再根据我们日常习惯,建立assets相关目录,示例如下:

而需要用的时候,这个静态文件的引用路径就是

/assets/img/xxxxx.ext

网站图标

将生成好的favicon.ico放到.vuepress/public/assets/img/中。

然后到.vuepress/config.js文件中添加一项如下:

head: [
        ['link', { rel: 'shortcut icon', type: "image/x-icon", href: "/assets/img/favicon.ico" }]
    ]

只要路径对,重新发布后就可以看到网站图标了。

导航栏

导航栏默认是带搜索框的,然后如果想新增,就在.vuepress/config.js文件中的themeConfig节点底下新增nav节点。

比如:

nav: 
[
    { text: '首页', link: '/' },
    { text: '百度一下', link: 'https://www.baidu.com' },
]

外部链接<a>标签的特性将默认包含target="_blank" rel="noopener noreferrer",你可以提供targetrel,它们将被作为特性被增加到<a>标签上。

// .vuepress/config.js
module.exports = {
  themeConfig: {
    nav: [
      { text: 'External', link: 'https://google.com', target:'_self', rel:'' },
      { text: 'Guide', link: '/guide/', target:'_blank' }
    ]
  }
}

侧边栏

自定义侧边栏

默认侧边栏是没有启用的,如果需要,在.vuepress/config.js文件中的themeConfig节点底下新增sidebar节点。

比如:

sidebar: 
[
    ['account/bizspark', 'BizSpark'],
    ['account/office', 'Office 365']
]


自动侧边栏

.vuepress/config.js文件中的themeConfig节点底下新增sidebar节点,设置成auto模式即可。

sidebar: 'auto'

其他效果

开启滑动动画

// themeConfig
smoothScroll: true

添加上次更新时间

// themeConfig
lastUpdated: '上次更新',

全局显示代码行号

.vuepress/config.js文件中添加节点markdown

markdown:{
    lineNumbers: true, // 显示代码行号
}

设置全局内容视图宽度

.vuepress路径新增styles文件夹,并新建文件palette.styl

填充内容,其中contentWidth的数值就是你要设置的默认最低内容视图宽度。

$contentWidth = 1000

多语言

在根目录新建文件夹zh-cnen-us两个文件夹,然后将对应语言的文件放到对应的文件夹里面。

配置导航栏,如果导航栏是一个Item项,它会呈现下拉样式,比如我们多语言就可以做成如下:

nav: 
[
    { text: '首页', link: '/' },
    {
        text: '语言',
        ariaLabel: 'Language Menu',
        items: [
          { text: '中文', link: '/zh-cn/' },
          { text: 'English', link: '/en-us/' }
        ]
    },
]

参考资料

posted @ 2020-08-07 23:46  TaylorShi  阅读(509)  评论(0编辑  收藏  举报