VuePress从零开始

5

VuePress

VuePress 由两部分组成:一个以 Vue 驱动的主题系统的简约静态网站生成工具,和一个为编写技术文档而优化的默认主题。它是为了支持 Vue 子项目的文档需求而创建的。

由 VuePress 生成的每个页面,都具有相应的预渲染静态 HTML,它们能提供出色的加载性能,并且对 SEO 友好。然而,页面加载之后,Vue 就会将这些静态内容,接管为完整的单页面应用程序(SPA)。当用户在浏览站点时,可以按需加载其他页面。

VuePress中文网

环境搭建

安装

Node.js版本需要>=8才可以。

npm install -g vuepress 或者在已有项目中安装
npm install vuepress -D

安装完成检测是否安装成功

vuepress -v
//vuepress v1.0.3

其他信息:

vuepress v1.0.3

Usage:
  $ vuepress <command> [options]

Commands:
  dev [targetDir]    start development server
  build [targetDir]  build dir as static site
  eject [targetDir]  copy the default theme into .vuepress/theme for customization.
  info               Shows debugging information about the local environment

For more info, run any command with the `--help` flag:
  $ vuepress dev --help
  $ vuepress build --help
  $ vuepress eject --help
  $ vuepress info --help

Options:
  -v, --version  Display version number 
  -h, --help     Display this message 

创建项目

mkdir VuePress
cd VuePress

初始化项目

通过npm init快速创建项目的pageage.json文件

npm init -y
{
  "name": "VuePress",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

新建docs文件夹

docs文件夹作为项目文档根目录,主要放置Markdown类型的文章和.vuepress文件夹。

mkdir docs

设置package.json

在script中添加dev启动和build打包脚本命令

"scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "dev": "vuepress dev docs",
    "build": "vuepress build docs"
  },

创建README.md

在docs里面创建README.md

cd docs
echo "## Hello VuePress" > README.md

创建.vuepress目录

npm run build

可直接打包构建README.md文件 并生成.vuepress

.vuepress 目录这是放置所有 VuePress 特有(VuePress-specific) 文件的地方。

创建config.js

不做任何配置的话,页面会显得过于简单,用户也无法方便地浏览网站;

配置 VuePress 站点的基本文件是 .vuepress/config.js,其中导出一个 JavaScript 对象:

touch config.js

目录结构

├── docs # 文档目录
│    ├── .vuepress //存放所有资源和打包结果
│   │         ├── dist //打包结果
│   │        ├── public //公共资源文件
│   │        ├── ...
│   │       └── config.js //配置文件
│   ├── demo //分类文档存储
│   │    ├── demo1.md
│   │    ├── ...
│   │    └── demon.md
│   └── README.md 
└── package.json//项目启动配置

基本配置

module.exports = {
    title: '文档管理', 
    description: '呵呵博客',
    head: [
        ['link', { rel: 'icon', href: '/logo.ico' }]
    ]
}

title

  • Type: string
  • Default: undefined

网站的标题。这将是所有页面标题的前缀,并显示在默认主题的导航栏中。

description

  • Type: string
  • Default: undefined

网站描述。这将在页面 HTML 中表现为一个 <meta> 标签。

head

  • Type: Array
  • Default: []

被注入页面 HTML <head> 额外的标签。每个标签可以用 [tagName, { attrName: attrValue }, innerHTML?] 的形式指定。例如,要添加自定义图标:

port

  • Type: number
  • Default: 8080

指定用于 dev 服务器的端口。

dest

  • Type: string
  • Default: .vuepress/dist

指定 vuepress build 的输出目录。

效果

导航配置

配置代码

你可以通过 themeConfig.nav 将链接添加到导航栏中:

module.exports = {
  
    themeConfig: {
        nav: [
          { text: '主页', link: '/' },
          { text: '测试', link: '/test/test.md' },
          { text: '百度', link: 'https://www.baidu.com' },
        ]
      }
}

可以添加远程连接 如:

{ text: '百度', link: 'https://www.baidu.com' },

也可以添加本地文件:

{ text: '测试', link: '/test/test.md' },

效果

侧边栏配置

基本配置

你可以省略 .md 扩展名,以 / 结尾的路径被推断为 */README.md 。该链接的文本是自动推断的(从页面的第一个标题或 YAML front matter 中的显式标题)。如果你希望明确指定链接文本,请使用 [link,text] 形式的数组。

themeConfig: {
    sidebar: [
        ['/', '简介'],
        ['/cst/cst.md', '车商通'],
        ['/new/index1.md', '发布新框架'],
        ['/feedback/feedback.md', '问题反馈']
    ]
}

注意:文件命名不要用index关键字

侧边栏组配置

使用对象将侧边栏链接分成多个组:

themeConfig: {
    sidebar: [
        ['/', '简介'],
        {
            title: "车商通",
            collapsable: false,
            children:[
                ['/cst/cst.md', '车商通'],
                ['/cst/draft.md', '草稿箱'],
                ['/cst/esc.md', '二手车']
            ]
        },
        {
            title: "新框架",
            collapsable: true,
            children:[
                ['/new/testindex1.md', '发布新框架'],
                ['/new/local/entry.md', '本地开发'],
                ['/new/feedback/feedback.md', '问题反馈']
            ]
        },

        ['/feedback/feedback.md', '问题反馈']
    ]
}

侧边栏组默认情况下是可折叠的。你可以强制一个组始终以 collapsable:false 打开。

多侧边栏

如果你希望为不同的页面组显示不同的侧边栏,请先将页面组织到目录中:

.
├─ README.md
├─ cst
│  ├─ README.md
│  ├─ draft.md
│  └─ esc.md
└─ new
   ├─ README.md
   ├─ local/entry.md
   └─ feedback/feedback.md

代码展示:

themeConfig: {
    nav: [
        { text: '主页', link: '/' },
        { 
            text: '技术',
            items: [
                { text: '车商通', link: '/cst/' },
                { text: '新框架', link: '/new/' }
            ]
        }
      ],
    sidebar: {
        '/cst/': [
            ['', '车商通'],
            ['draft', '草稿箱'],
            ['esc', '二手车']
        ],
        '/new/': [
            ['', '发布新框架'],
            ['local/entry.md', '本地开发'],
            ['feedback/feedback.md', '问题反馈']
        ]
    }
}

效果:

注意:访问入口进来默认加载README

完整示例

module.exports = {
    base: "/docSynopsis/", //文件访问地址
    dest: "docSynopsis", //文档打包输出目录
    title: '文档系统使用手册', //文档title
    description: '文档系统使用手册',
    head: [
        ['link', { rel: 'icon', href: '/favorite.jpg' }]
    ],
    themeConfig: {
        repo: 'vuejs/vuepress', // github链接配置
        nav: [
            { text: '主页', link: '/home/instructions' }
          ],
        sidebar: [
            ['/home/instructions', '简介'],
            {
                title: "系统功能",
                collapsable: false,
                children:[
                    ['/home/add', '文档添加'],
                    ['/home/list', '文档列表'],
                    ['/home/edit', '文件编辑'],
                    
                ]
            },
            ['/tool/igit', 'igit公共账号'],
            {
                title: "文档工具",
                collapsable: false,
                children:[
                    ['/tool/gitbook', 'gitbook简介'],
                    ['/tool/vuepress', 'vuepress简介']
                ]
            }
        ]
    }
};

效果:
图片描述


如果觉得我的文章对你有用,请随意赞赏

你可能感兴趣的

载入中...