• Home
  • home > tools > Bundler > vite >

    vitepress搭建markdown文档博客

    Author：zhoulujun Date：

    目前主流搭建文档站点的方式：Gatsby - 以 GraphQL 为核心，功能相当完善，插件生态丰富。但学习曲线高（React）Docusaurus - Meta

    VitePress剪辑

    VitePress 是 VuePress 的下一代框架 ，是支持vue 3.0 的 web 网站框架。

    • 基于 Vite 而不是 Webpack 所以更快的启动时间，热重载等

    • 使用 Vue3 来减少 JS 的有效负载

    vuePress=webpack+vue2,vitePress=vite+vue3html

    目前主流搭建文档站点的方式：

    • Gatsby - 以 GraphQL 为核心，功能相当完善，插件生态丰富。但学习曲线高（React）

    • Docusaurus - Meta 公司出品。功能强大，与 Gatsby 相似（React）

    • dumi - 一款 UmiJS 生态中的组件开发文档工具（React）

    • Nextra - 一个基于 Next.js 的静态站点生成器。（React）

    • VuePress - 包含由 Vue 驱动的主题系统和插件 API，另一个部分是为书写技术文档而优化的默认主题（Vue）

    • VitePress - 对 VuePress 进行了不少的改进。VitePress 旨在降低当前 VuePress 的复杂性，并从其极简主义的根源重新开始。（Vue）

    除了 VitePress 之外，其他都是用 Webpack 作为开发服务器。一个只有几页的简单文档站点启动开发服务器所花费的时间变得难以忍受。即使是 HMR 更新也可能需要几秒钟才能反映在浏览器中。Vite 的出现很好地解决了这些问题：近乎即时的服务器启动、仅编译所服务页面的按需编译以及闪电般快速的 HMR。

     VuePress v1 在本质上是一个 Webpack 应用程序。即便只有两个页面，它也是一个完整的正在编译的 Webpack 项目(包括全部主题源文件)。更糟糕的是，当项目有不少页面时，服务器必须首先彻底编译每一个页面，而后才能显示任何内容

    Vite 很好地解决了这些问题:服务器几乎当即启动，按需编译只编译所服务的页面，以及快速的 HMR。

    有了 Vite 和 Vue 3，真的是时候从新考虑“Vue 驱动的静态站点生成器（vue系列的说明文档几乎都是这样生成的）


    创建博客：

    mkdir blog-vitepress
cd blog-vitepress

npm init -y
npm i -D vitepress

yarn init -y
yarn add -D vitepress

    将 vitepress 执行命令添加到执行脚本中

    "scripts": {
  "dev": "vitepress dev docs --open",
  "build": "vitepress build docs",
  "serve": "vitepress serve docs"
}

    根目录创建 docs 目录，创建第一个 md 文件（网站首页的配置和内容），可以命令行活在文件中手动创建

    mkdir docs
echo '# Hello World' > docs/index.md

    启动项目

    npm run dev

    具体文档文件结构



    vite-plugin-react-pages

    其实也可以通过 https://github.com/vitejs/vite-plugin-react-pages 生成

    vite-plugin-react-pages(vite-pages) 是一个由 vite 提供支持的 React 应用程序框架。它非常适合：

    • 博客网站

    • 组件库或产品的文档站点

    • React 组件的 Demo 演示

    vite-pages 默认提供了三种模板，可以选择初始化app（应用）、lib（组件库）、lib-monorepo

    npm init vite-pages [仓库名] --template [模板名]

    我们执行 npm init vite-pages library-demo --template lib 生成了一个典型的 Vite 结构的项目，有熟悉的 vite.config.ts、pages 文件夹等

    该插件所有明确的依赖包作用：

    • @mdx-js/mdx MDX的实现

    • @mdx-js/react 作为 MDX 的 React 实现。

    • vite-plugin-mdx Vite 支持 MDX 的插件

    • vite-plugin-react-pages 文档插件核心实现

    • vite-pages-theme-doc 官方的文档主题。依赖 react-router-dom ^5.0.0 版本

    pages 目录为文档入口。文件式路由约定用 $ 符号的文件名结尾来识别为一个文档页面

    .ts|.tsx|.js|.jsx|.md|.mdx 只要 $ 是扩展名前的最后一个字符，所有文件扩展名都有效。

    index$.tsx/
    .tsx 效果相同）/
    page-one$.tsx/page-one
    page-two$.md/page-two
    dir-name/page-three$.mdx/dir-name/page-three
    dir-name/[id]/index$.tsx/dir-name/:id

    pages 目录中还存在一个特殊的入口 _theme.tsx 用来配置当前文档的主题，vite-pages 默认使用了 vite-pages-theme-doc 官方主题。如果自定义需求不大，可以通过配置官方主题的参数来实现常规的功能。比如配置 logo、顶部链接、左侧菜单等。

    具体阅读：https://vitejs.github.io/vite-plugin-react-pages/


    项目配置

    创建一个配置文件，在docs中新建一个 .vitepress 文件夹，里面创建一个 config.js 文件(VitePress 站点的基本文件是.VitePress/config.js，它应该导出一个 JavaScript 对象：) 查看配置参考以得到完整的选项列表

    // vitepress/config.js
module.exports = {
  title: "我的博客",// 网站标题
  description: '我的vitepress博客.', //网站描述
  base: '/', //  部署时的路径 默认 /  可以使用二级地址 /base/
  // lang: 'en-US', //语言
  // 网页头部配置，引入需要图标，css，js
  head: [
    // 改变title的图标
    [
      'link',
      {
        rel: 'icon',
        href: '/img/linktolink.png',//图片放在public文件夹下
      },
    ],
  ],
  // 主题配置
  themeConfig: {
    repo: 'vuejs/vitepress', // 你的 github 仓库地址，网页的右上角会跳转
    //   头部导航
    nav: [
      { text: '首页', link: '/' },
      { text: '介绍', items:[{ text: '关于', link: '/brief/about/' },] }, // items 可以一直嵌套
      { text: '关于', link: '/about/' },
    ],
    //   侧边导航
    sidebar:{
    "/":[
        {
            text:"简介",
            link:'/intro/index'
        },
        {
            text:"新手入门",
            children:[
                {
                    text:'安装与使用',
                    link:'/intro/install-and-usage'
                },
            ]
        },
        {
            text:"命令",
            children:[
                {
                    text:'命令使用',
                    link:'/intro/command-info'
                },
                {
                    text:'自定义命令',
                    link:'/intro/custom-command'
                }
            ]
        },
    ]
}
  }
}


    博客开发注意事项

    基础路径

    若是站点部署到非根 URL，则须要在.vitepress/config.js 中设置 base 选项。例如，若是您计划将站点部署到https://foo.github.io/bar/，则应将base设置为“/bar/”（始终以斜杠开头和结尾）。

    对于基本 URL，要在公共场合引用图像，必须使用/bar/image.png 这样的 URL。但若是你决定改变基础，这是脆弱的。为了帮助实现这一点，VitePress 提供了一个内置的助手$withBase（注入到 Vue 的原型中），它能够生成正确的路径：

    <img :src="$withBase('/foo.png')" alt="foo" />


    Markdown 拓展

    内部链接

    内部连接转换为路由器连接，用于 SPA 导航。此外，每一个子目录中包含的每一个 index.md 都将自动转换为 index.html，并带有相应的 URL/。

    例如，给定如下目录结构：

    .
├─ index.md
├─ foo
│  ├─ index.md
│  ├─ one.md
│  └─ two.md
└─ bar
   ├─ index.md
   ├─ three.md
   └─ four.md

    提供其中之一 foo/one.md

    [Home](/) <!-- 跳转到根部的 README.md -->
[foo](/foo/) <!-- 跳转到 foo 文件夹的 index.html -->
[foo heading](./#heading) <!-- 跳转到 foo/index.html 的特定标题位置 -->
[bar - three](../bar/three.md) <!-- 具体文件可使用 .md 结尾（推荐） -->
[bar - four](../bar/four.html) <!-- 也能够用 .html -->


    页面后缀

    默认状况下，生成的页面和内部连接的后缀是.html。

    外部连接

    出站的连接自动得到target=" blank" rel="noopener noreferrer

    YAML frontmatter 

    具体查看：https://jekyllrb.com/docs/front-matter/

    注意的是采用三虚线必须放置在 markdown 文件的 最上面

    ---
title: Blogging Like a Hacker
lang: en-US
---


    frontmatter

    可供选择的 frontmatter 格式

    ---
title: tags
date: 2019-08-13 09:39:50
type: tags
layout: tag
---

# Hello VitePress
# {{ $frontmatter.date }}

    任何包含 YAML frontmatter 块的 Markdown 文件都将被 gray matter 处理。frontmatter 必须位于 Markdown 文件的顶部，而且必须采用三条虚线之间的有效 YAML 集的形式。例子：

    $frontmatter 很重要，vitePress 只识别这个----三条虚线块有且只有一个

    在三虚线之间，您能够设置预约义的变量，甚至建立您本身的自定义变量。这些变量能够经过$frontmatter 变量来使用。这里有一个例子，你能够在你的 Markdown 文件中使用它

    JSON 前端语法

    VitePress 还支持 JSON 前端语法，以花括号开始和结束【俩种写法不能共存】

    ---
{
  "title": "Blogging Like a Hacker",
  "editLink": true
}
---

# {{ $frontmatter.title }}


    预约义的变量

    具体查看：https://vitepress.vuejs.org/guide/frontmatter.html#title

    代码展示

    Prism 网站上有有效语言的列表上有的，都支持

    ```js{1,4,6-7}
export default {
  data () {
    return {
      msg: 'Highlighted!'
    }
  }
}
```

    还能够指定多个单行、范围或同时指定

    • 行范围:例如{5-8}，{3-10}，{10-17}

    • 多个单行:例如{4,7,9}

    • 行范围和单行:例如{4,7-13,16,23-27,40}

    进阶配置

    VitePress 使用 markdown-it 来渲染 Markdown，上述大多数的拓展也都是经过自定义的插件实现的。想要进一步的话，你能够经过 .vitepress/config.js 的 markdown 选项，来对当前的 markdown-it 实例作一些自定义的配置：

    module.exports = {
  markdown: {
    // markdown-it-anchor 的选项
    anchor: { permalink: false },

    // markdown-it-toc 的选项
    toc: { includeLevel: [1, 2] },

    config: (md) => {
      // 使用更多的 markdown-it 插件!
      md.use(require('markdown-it-xxx'))
    }
  }
}


    搜索配置

    先查看：https://vitepress.vuejs.org/config/algolia-search.html

    申请账号：https://docsearch.algolia.com/apply/，配置：

    module.exports = {
  themeConfig: {
    algolia: {
      apiKey: 'your_api_key',
      indexName: 'index_name'
    }
  }}

    就可以体验

    主题插件支持

    请先查看 https://vitepress.vuejs.org/guide/theming.html#using-a-custom-theme


    vitepress-theme-demoblock 插件, github 地址

    npm install -D vitepress-theme-demoblock
# or
yarn add -D vitepress-theme-demoblock

    配置 config.js

    module.exports = {
  markdown: {
    config: (md) => {
      const { demoBlockPlugin } = require('vitepress-theme-demoblock')
      md.use(demoBlockPlugin)
    }
  }
}

    注入主题与插件

    在 docs/.vitepress/theme/index.ts 中写入如下代码，其中 register-components.js 不需要自己创建，在 package.json 中注入脚本，执行脚本自动生成在 docs/.vitepress/theme 目录下

    "scripts": {
  "register:components": "vitepress-rc"
}

    执行 npm run register:components

    // docs/.vitepress/theme/index.ts

// 导入vitepress-theme-demoblock主题，并注册组件(包含主题中默认的组件)。
import Theme from 'vitepress/dist/client/theme-default'

// 导入主题样式
import 'vitepress-theme-demoblock/theme/styles/index.css'
// 想引入全局自己的 css 文件，也可以在这里引入

// 导入插件的主题
import { registerComponents } from './register-components.js'

export default {
  ...Theme,
  enhanceApp({ app }) {
    registerComponents(app)
  }
}

    使用

    在需要展示的 demo 中的 index.md 文件中使用特定的语法包裹代码，可以自动生成组件 demo 展示

    # Button 按钮

:::demo 使用`type`，`plain`，`round`来定义 Button 的样式

```vue
<template>
  <my-button style="color: red">按钮1</my-button>
  Middle
  <my-button type="size">按钮2</my-button>
  Large
  <my-button>按钮3</my-button>
  Disabled
  <my-button disabled>按钮4</my-button>
</template>
:::

    默认支持 vue 语法， 想修改的话需要修改配置：

    md.use(demoBlockPlugin, {  lang: 'ts'})

    但是这里有个限制，智能识别一种语法结构，想到会有 js、 ts、 json 等多种语法，所以改了下解析结构，改成了数组




    参考文章：

    https://miyauchi.dev/posts/start-vitepress/

    使用 vitepress + github Pages搭建自己的博客网站 https://juejin.cn/post/7038581771503403022

    「VitePress」极简博客搭建   https://juejin.cn/post/6896382276389732359

    基于 vite 的组件文档编写神器，又快又省心 https://jishuin.proginn.com/p/763bfbd72e9c

     VitePress 学习(全面拥抱vite)---翻译 https://juejin.cn/post/6965510644007665671




    转载本站文章《vitepress搭建markdown文档博客》,
    请注明出处：https://www.zhoulujun.cn/html/tools/Bundler/vite/8773.html

    收藏
    上一篇：新一代构建工具(3)：Vite站在巨人的肩膀——vite快的理由
    下一篇：vite启动localhost:5000 responds with http status 403无法访问