vite-plugin-doc-preview

vite-plugin-doc-preview 是基于 Vite 插件机制实现对 markdown 文件内容进行转换。核心通过 marked 结合 hightlight.js 实现代码高亮和美化。并且可让文档中带有如 preview 指定标识的 markdown 代码块替换为组件，体验预览效果。支持 Vue 和 React 框架

示例

https://337547038.github.io/vite-plugin-doc-preview/

安装使用

安装依赖

1npm install vite-plugin-doc-preview -D

2# or
3pnpm install vite-plugin-doc-preview -D

4# or
5yarn install vite-plugin-doc-preview -D

使用配置

在 Vue 中使用

1// vite.config.ts
2import { defineConfig } from 'vite'
3import Vue from '@vitejs/plugin-vue'
4import MarkedPreview from 'vite-plugin-doc-preview'
5
6export default defineConfig({
7  plugins: [
8    Vue({
9      include: [/\.vue$/, /\.md$/],
10    }),
11    MarkedPreview()
12    // 可根据需要设置参数，可选
13    /*MarkedPreview({
14      marked:{}, // marked转换options，可参考https://marked.js.org/
15      component:false // 是否自定义预览组件，默认false
16      previewId:'vue preview' // 预览标识，默认vue preview
17    })*/
18  ]
19})

在 React 中使用

1// vite.config.ts
2import { defineConfig } from 'vite'
3import react from '@vitejs/plugin-react';
4import MarkedPreview from 'vite-plugin-doc-preview'
5
6export default defineConfig({
7  plugins: [
8    react(),
9    MarkedPreview({mode:'react'})
10    // 可根据需要设置参数，可选
11    /*MarkedPreview({
12      marked:{}, // marked转换options，可参考https://marked.js.org/
13      component:false // 是否自定义预览组件，默认false
14      previewId:'vue preview' // 预览标识，默认vue preview
15    })*/
16  ]
17})

引入样式

在适当组件页面引入高亮样式，如 main.ts　中。其他主题风格可参考 highlight.js 引入对应主题

1import "vite-plugin-doc-preview/style/style.css"

代码预览标识

给需要预览的 markdown 文档代码块加上指定标识，如 vue preview 。其他标识可在vite.config.ts配置中修改

如 README.md 文件内容为：

1
2下方代码块将会被解析为 Vue 组件并展示预览效果和代码高亮美化
3
4```vue preview
5<template>{{value}}</template>
6<script setup>
7 import {ref} from 'vue'
8 const value = ref('hello 我是Vue模板')
9</script>
10```
11
12或者为React 
13
14```jsx preview
15const Example = ()=>{
16 return (<div>hello 我是React模板</div>)
17}
18export default Example
19```
20

路由配置

1 [
2  {
3    path: '/',
4    name: '/md',
5    component: () => import('./views/README.md')
6  }
7]

自定义预览组件

Vue 预览组件

如果默认的样式不能满足需求，可以全局注册一个 CodePreview 组件来代替默认组件。

设定自定义预览组件时

1//1. vite.config.ts中配置：
2MarkedPreview({component:true})  // 传入参数，表示为自定义预览组件
3
4//2.　main.ts中
5import CodePreview from 'xxxxx'
6app.component('CodePreview', CodePreview)　//　注册自己的自定义好的预览组件

CodePreview 需要按约定支持如下 props 和 slot

• props
  • code string 代码块的原始代码，代码已经encodeURIComponent处理
• slot
  • default 代码块生成的 vue 组件
  • code 代码块经过高亮转换的 html

React 预览组件

React 没有全局注册的概念，可通过 component 传入预览组件路径，如

1// 1.vite.config.ts中配置
2MarkedPreview({component:'@/component/codePreview.jsx'})  // 传入参数，表示为自定义预览组件

预览组件需按约定支持如下 props 和 children

• props
  • code string 代码块的原始代码，代码已经encodeURIComponent处理
• children
  • children[0] 代码块生成的 React 组件
  • children[1] 代码块经过高亮转换的 html