初次尝试Vuepress

小小操作手
352 阅读5分钟

vuepress官网:

介绍

vuepress是Vue作者为了支持Vue及其子项目的文档需求而写的一个极简静态网站生成器。Vuepress的界面十分简洁，并且网站的结构非常的简单，非常容易上手

创建一个项目

创建一个demo目录

mkdir vuepress-demo
cd vurpress-demo

//初始化你的项目

yarn init 
OR
npm init

安装

yarn add -D vuepress 
# Or
npm install -D vuepress

创建一个docs目录，并创建第一个README.md文件，这个文件将展示的你主页内容；

mkdir docs && echo '# Hello VuePress' > docs/README.md

在你的package.json文件的scripts中添加

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

//docs:dev：是用于本地预览链接

//docs:build：是用于编译打包，将我们目录结构的.md文件编译成.html文件。

本地预览

yarn docs:dev # npm run docs:dev

使用TypeScript

值得注意的一点是，我在项目中用到了typescript，所以需要格外的配环境

www.karltarvas.com/2020/05/12/…

  • 安装

//安装vuepress的插件和vue支持的类型

yarn add vuepress vuepress-plugin-typescript vuepress-types --dev
  • 在vuepress中配置Vue shims，为了支持.vue文件
// docs/.vuepress/shims-vue.d.ts
declare module '*.vue' {
    import Vue from 'vue';
    export default Vue;
}

// docs/.vuepress/config.js
const path = require('path');

const projectRoot = process.cwd();
const alias = path.resolve(projectRoot, 'src');

module.exports = {
    // If you need to configure any plugins etc, this is the call to do so
    configureWebpack(config) {
        // Solely to speed up Vuepress, reenable if you need to debug your setup
        config.devtool = false;
        // Match standard Vue CLI aliasing
        config.resolve.alias['@'] = alias;
    },
    plugins: [
        ['vuepress-plugin-typescript', {
            tsLoaderOptions: {
                // Vuepress compilation is ridiculously slow without this, type checking belongs in development not documentation anyway
                transpileOnly: true,
                compilerOptions: {
                    // Vuepress needs an older target (as opposed to esnext) to correctly transpile optional chaining and nullish coalescing
                    'target': 'ES2019',
                },
            },
        }],
    ],
}

目录结构

我们以官方给出的例子展示：

  • 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文件中的README.md文件中加入官方给的例子

主页 Home

---
home: true 
heroImage: /hero.png 
heroText: Hero 标题
tagline: Hero 副标题
actionText: 快速上手 →
actionLink: /zh/guide/
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
---
  • home：是否默认主页（默认主题提供了一个首页的布局，所以你想将这个当作主页，需要给它添加home:true，
  • 标题和副标题：可以通过不添加属性或者内容输入null来禁用

导航栏 Nav

可以通过设置config.js目录中themeConfig来添加

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

// 值得注意的是，在vuepress中的根目录是docs，在路由导向时：/代表的根目录，

//禁用导航栏

---
navbar: false
---

侧边栏 Asider

想要使 侧边栏（Sidebar）生效，需要配置 themeConfig.sidebar，基本的配置，需要一个包含了多个链接的数组：

// .vuepress/config.js
module.exports = {
  themeConfig: {
    sidebar: [
      '/',
      '/page-a',
      ['/page-b', 'Explicit link text']
    ]
  }
}

如果想展现一个title的下拉形式,需要以一个对象的形式输入，含有title表示下拉标题，children表示导航链接，指向public目录中的.md文件

sidebar:[
          {
             title: "快速上手",
             children: [
                "/guide/Add",
                "/guide/Hello",
    	],
	},
]

目录结构

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

在Markdown中使用Vue

在Markdown使用我们Vue组件展示，我自己写的UI的样式， 首先我们需要在.vurpress目录中创建一个components的文件里面存放我们的.vue组件

// docs/.vuepress
mkdir components 
cd components
touch OtherComponent.vue

这里值得注意的是，在其他Vuepress的md文档中我们可以直接展示我们的组件，通过我们在components文件中.vue的名字直接获取到

// 展示是通过标签的形式，很Vue
<OtherComponent></OtherComponent>

游览器访问限制

如果你正在使用，或者需要展示一个对于 SSR 不怎么友好的组件（比如包含了自定义指令），你可以将它们包裹在内置的 组件中：

  <ClientOnly>
  <NonSSRFriendlyComponent/>
  </ClientOnly>

部署

上传到GitHub上

在docs/.vuepress/config.js设置 正确的base

  • 发布上传（没有仓库）

https://.github.io/，则可以省略这一步，因为 base 默认即是 "/"

  • 发布上传（上传已有仓库） 需要将base设置为你的/仓库名/

自动部署（选择自己上传方式1，没有仓库，2.已有仓库）

#!/usr/bin/env sh

# 确保脚本抛出遇到的错误
set -e

# 生成静态文件
npm run 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:gh-pages

cd -
avatar
文章
阅读
粉丝