jaskang/vite-plugin-markdown-preview

vite/vitepress markdown code preview

vite-plugin-markdown-preview

基于 vite/vitepress 的 markdown 代码块预览插件。

vite-plugin-markdown-preview 能将 markdown 文档中带有 preview 标识的 vue 代码块替换为 vue 组件。

文档：https://markdown-preview.jaskang.vip

示例

安装

安装依赖

npm install vite-plugin-markdown-preview
# or
pnpm install vite-plugin-markdown-preview

在 Vitepress 中使用

在 .vitepress/config.ts 中配置插件

import { defineConfig } from 'vitepress'
import MarkdownPreview from 'vite-plugin-markdown-preview'

export default defineConfig({
  vite: {
    plugins: [MarkdownPreview()],
  },
})

在 Vite 中使用

vite-plugin-markdown-preview 依赖 unplugin-vue-markdown 的 markdown 解析能力, 所以还需要安装 unplugin-vue-markdown

// vite.config.ts
import { defineConfig } from 'vite'
import Vue from '@vitejs/plugin-vue'
import Markdown from 'unplugin-vue-markdown/vite'
import MarkdownPreview from 'vite-plugin-markdown-preview'

const config = defineConfig({
  plugins: [
    Vue({
      include: [/\.vue$/, /\.md$/], // <-- allows Vue to compile Markdown files
    }),
    Markdown({
      /* options */
    }),
    MarkdownPreview(),
  ],
})

export default config

代码预览标识

给需要预览的 vue 代码块加上 preview 标记。

如 test.md 文件内容为：

_下方代码块将会被解析为 vue 组件并展示_

```vue preview
<template>我是 vue 模板</template>
```

经过 vite-plugin-markdown-preview 处理后：

自定义预览组件

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

app.component('CodePreview', MyCodePreview)

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

• props
  • lang string 代码块的 lang
  • meta string // 代码块的 meta 信息
  • code string // 代码块的原始代码
• slot
  • default 代码块生成的 vue 组件将会以 slots.default 传递过来
  • code 代码块经过高亮转换为 html 将会以 slots.code 传递过来

示例自定义展示组件:

vite-plugin-markdown-preview's Issues

为什么我的表格渲染出来没有边框，是否还需要配置什么

import {defineConfig} from "vite";
import vue from "@vitejs/plugin-vue";
import vitePluginVuedoc, {vueDocFiles} from "vite-plugin-vuedoc";

export default defineConfig({
    plugins: [
        vitePluginVuedoc({}),
        vue({
            include: [...vueDocFiles],
        }),
    ]
});

在windows上有路径问题

地址会变成一串

Missing a Markdown theme style?

Could not load path (imported by node_modules\vite-plugin-vuedoc\dist\markdownToVue.js)

1.yarn add vite-plugin-vuedoc

2. //vite.config.ts
   import vitePluginVuedoc from 'vite-plugin-vuedoc'
   const config = {
   base: "./",
   assetsDir: "example/assets",
   plugins: [
   vitePluginVuedoc({
   prism: {
   theme: "okaidia",
   },
   }),
   ]
   }
   export default config

3.yarn dev

yarn run v1.22.10
$ vite
[vite] Optimizable dependencies detected:
vite-plugin-vuedoc, vue

[vite] Dep optimization failed with error:
Could not load path (imported by node_modules\vite-plugin-vuedoc\dist\markdownToVue.js): ENOENT: no such file or directory, open 'C:\Users\dengjiali\Documents\emrwriter\emrwriter-vite\path'
[Error: Could not load path (imported by node_modules\vite-plugin-vuedoc\dist\markdownToVue.js): ENOENT: no such file or directory, open 'C:\Users\dengjiali\Documents\emrwriter\emrwriter-vite\path'] {
errno: -4058,
code: 'ENOENT',
syscall: 'open',
path: 'C:\Users\dengjiali\Documents\emrwriter\emrwriter-vite\path',
watchFiles: [
'C:\Users\dengjiali\Documents\emrwriter\emrwriter-vite\node_modules\vue\dist\vue.runtime.esm-bundler.js',
'C:\Users\dengjiali\Documents\emrwriter\emrwriter-vite\node_modules\vite-plugin-vuedoc\dist\index.js',
'C:\Users\dengjiali\Documents\emrwriter\emrwriter-vite\node_modules\@VUE\runtime-dom\dist\runtime-dom.esm-bundler.js',
'C:\Users\dengjiali\Documents\emrwriter\emrwriter-vite\node_modules\@VUE\shared\dist\shared.esm-bundler.js',
'\x00commonjsHelpers.js',
'C:\Users\dengjiali\Documents\emrwriter\emrwriter-vite\node_modules\@VUE\runtime-core\dist\runtime-core.esm-bundler.js',
'C:\Users\dengjiali\Documents\emrwriter\emrwriter-vite\node_modules\@VUE\reactivity\dist\reactivity.esm-bundler.js',
'C:\Users\dengjiali\Documents\emrwriter\emrwriter-vite\node_modules\vite-plugin-vuedoc\dist\server.js',
'C:\Users\dengjiali\Documents\emrwriter\emrwriter-vite\node_modules\vite-plugin-vuedoc\dist\build.js',
'\x00C:\Users\dengjiali\Documents\emrwriter\emrwriter-vite\node_modules\vite-plugin-vuedoc\dist\server.js?commonjs-proxy',
'\x00C:\Users\dengjiali\Documents\emrwriter\emrwriter-vite\node_modules\vite-plugin-vuedoc\dist\build.js?commonjs-proxy',
'\x00C:\Users\dengjiali\Documents\emrwriter\emrwriter-vite\node_modules\vite-plugin-vuedoc\dist\markdownToVue.js?commonjs-proxy',
'C:\Users\dengjiali\Documents\emrwriter\emrwriter-vite\node_modules\vite-plugin-vuedoc\dist\markdownToVue.js',
'\x00C:\Users\dengjiali\Documents\emrwriter\emrwriter-vite\node_modules\debug\src\browser.js?commonjs-proxy',
'\x00C:\Users\dengjiali\Documents\emrwriter\emrwriter-vite\node_modules\slash\index.js?commonjs-proxy',
'C:\Users\dengjiali\Documents\emrwriter\emrwriter-vite\node_modules\debug\src\browser.js',
'C:\Users\dengjiali\Documents\emrwriter\emrwriter-vite\node_modules\slash\index.js',
'C:\Users\dengjiali\Documents\emrwriter\emrwriter-vite\node_modules\fs-extra\lib\index.js',
'\x00C:\Users\dengjiali\Documents\emrwriter\emrwriter-vite\node_modules\fs-extra\lib\index.js?commonjs-proxy',
'C:\Users\dengjiali\Documents\emrwriter\emrwriter-vite\node_modules\vite-plugin-vuedoc\dist\remark\index.js',
'\x00C:\Users\dengjiali\Documents\emrwriter\emrwriter-vite\node_modules\vite-plugin-vuedoc\dist\remark\index.js?commonjs-proxy',
'\x00C:\Users\dengjiali\Documents\emrwriter\emrwriter-vite\node_modules\debug\src\common.js?commonjs-proxy',
'C:\Users\dengjiali\Documents\emrwriter\emrwriter-vite\node_modules\debug\src\common.js',
'path',
'\x00path?commonjs-proxy'
]
}
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

how to fix this

Error: Cannot find module 'debug'

报错：```
error when starting dev server:
Error: Cannot find module 'debug'
Require stack:

• 项目路径\node_modules\vite-plugin-vuedoc\dist\markdown-it\index.js
• 项目路径\node_modules\vite-plugin-vuedoc\dist\markdownToVue.js
• 项目路径\node_modules\vite-plugin-vuedoc\dist\plugin.js
• 项目路径\node_modules\vite-plugin-vuedoc\dist\index.js

"vue": "^3.2.3",
"typescript": "^4.3.2",
"vite": "^2.5.0",

.md 的demo中，如果带有 css就会报错。

.md中的代码

<template>
   <div class="docs-div">test</div>
</template>
<style lang="scss" scoped>
.docs-div {
    height: 40px;
    line-height: 40px;
    text-align: center;
}
</style>

---

改为：

<template>
   <div class="docs-div">test</div>
</template>

<style scoped>
.docs-div {
    height: 40px;
    line-height: 40px;
    text-align: center;
}
</style>

也是报错

加载md文件报错

当md文件里面使用···vue demo时就会报错

vite版本为2.7.2
vue版本为3.2.25

3.0.2版本启动报错

你好新建vite项目引入报错是什么原因

报错内容

error when starting dev server:
Error: Cannot find module 'debug'
Require stack:
- D:\workspace_vite\climb-ui\node_modules\vite-plugin-vuedoc\dist\markdown-it\index.js
- D:\workspace_vite\climb-ui\node_modules\vite-plugin-vuedoc\dist\markdownToVue.js    
- D:\workspace_vite\climb-ui\node_modules\vite-plugin-vuedoc\dist\plugin.js

package.json

{
  "version": "0.0.0",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "serve": "vite preview"
  },
  "dependencies": {
    "vite-plugin-vuedoc": "^3.1.3",
    "vue": "^3.0.5"
  },
  "devDependencies": {
    "@vitejs/plugin-vue": "^1.2.4",
    "@vue/compiler-sfc": "^3.0.5",
    "vite": "^2.4.0"
  }
}

vite.config.js

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

import vitePluginVuedoc, { vueDocFiles } from 'vite-plugin-vuedoc'

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    vitePluginVuedoc(), // 1. Must be loaded before @vitejs/plugin-vue
    vue({
      include: [...vueDocFiles] // 2. Must include .md | .vd files
    })]
})

您好，请问可以支持tsx组件的写法吗？

就组件本身来说，大多时候采用的写法都为tsx的写法，本人也喜欢这种开发方式，所以在写文档和写组件时，总会来回切换，很不习惯，也在想如何可以解析tsx的代码。

打包发布需要额外配置什么吗，为通过npm run build打包后，无法跳转到md页面，报错Error: Unknown variable dynamic import: ../docs/form/index.md

vue-router.global.prod.js:6 Error: Unknown variable dynamic import: ../docs/form/index.md
    at index.e6f2f309.js:1
    at new Promise (<anonymous>)
    at component (index.e6f2f309.js:1)
    at Re (vue-router.global.prod.js:6)
    at vue-router.global.prod.js:6

show/hidden切换问题

如下代码：
/packages/vite-plugin-vuedoc/src/markdown-it/index.ts

{{ ${id}Height > 0 ? 'hidden' : 'show' }}

切换显示隐藏有问题，${id}Height为字符类型，建议修改为：

{{ ${id}Height > '0px' ? 'hidden' : 'show' }}

md files hmr not working in Windows

Hi, JasKang

If I make some changes in button.docs.md, for instance

  # vite-plugin-vuedoc

into

  # vite-plugin-vuedoc-md-hmr-in-windows

This request : /src/components/button.docs.md?type=template

would still remain the same in Windows

However, it works well in Mac

TypeError: Failed to fetch dynamically imported module

hello，an error when i route a md file include:

我是 vue 模板
error details：

TypeError: Failed to fetch dynamically imported module： http://.../test.md?import

and

GET http://.../test.md.DemoBlockI0.vue net::ERR_ABORTED 404 (Not Found)

please help me，thanks! (救救孩纸吧QAQ)

组件在windows上不好使

组件在windows上不好使
const resolve = (...args: string[]) => {
let ret = path.resolve(path.dirname(file), ...args)
ret = path.relative(root, ret)
console.log(ret)
return /${ret}
}

在windows 上该函数返回的路径为 /xx\xxx\xxxxx\

Path resolution on Windows is incorrect

reason

1. path solution ( code line) should add slash
2. markdowntovue (code line) have the same problem, But I haven't found the cause of the problem yet

---

About reason 2：

markdownToVue.ts code line

console in mac with vite:rewrite

vite:rewrite     "/Users/xiangxiao/Documents/work/workspace/vite-plugin-vuedoc/playground/src/components/button.docs.md/VUEDEMO_0" --> "/src/components/button.docs.md/VUEDEMO_0" +2ms

in windows

vite:rewrite     "E:/workspace/vite-plugin-vuedoc/playground/src/components/button.docs.md/VUEDEMO_0" --> "/@modules/E:/workspace/vite-plugin-vuedoc/playground/src/components/button.docs.md/VUEDEMO_0?import" +7ms

maybe its vite problem with reg at codeline

bareImportRE just test path in mac

or we should change to relative path

使用报 Cannot read property 'wrapperClass' of undefined

"vite": "^2.3.0"
"vite-plugin-vuedoc": "^3.1.3"

使用报该错误，按照 readme 来进行配置，望指正下是那里的问题

能否自定义预览代码中的导入模块？

您好！我正在做一个自定义组件库的文档，使用到了您的预览组件，非常棒，很好用。

但我遇到了一个问题，预览代码中我需要告知用户从我的组件库中导入一个需要使用的配置，并传递给组件，文档中的代码如下所示：

<template>
    <MyComponent :config="ConstConfig" />
</template>

<script lang="ts" setup>
import { ConstConfig } from 'my-lib'; //导入预设的配置，并传递给组件
</script>

现在遇到了一个问题，我希望这个组件可以在文档中实时预览，但实际上代码并不能运行，因为vite找不到我的依赖my-lib。

我把组件库代码和文档放在同一个项目中，方便管理，如果我使用相对路径例如 import { ConstConfig } from '../../my-lib'; 则可以正常导入并显示预览，但这样肯定不行因为看文档的用户如果看到这个相对导入，会觉得很奇怪，并且他如果直接复制代码到他的项目中，就不能导入，如果是库的名称'my-lib', 就没有这个问题。

所以想问问作者 vite-plugin-markdown-preview 有没有什么配置可以增加自定义导入库，比如设置一个配置，可以把导入库映射到本地文件上

是否可以添加对vue2的支持？

是否可以添加对vue2的支持？

与vite2.0 不兼容

vite2.0修改了部分api 是否有更新计划

如何给a标签添加 target="_blank" 属性？？

如何给a标签添加 target="_blank" 属性？？

版本有缺陷

error when starting dev server:
Error [ERR_REQUIRE_ESM]: require() of ES Module

substr 截取路径导致的 bug

关于 plugin.ts 中 resolveId、transform、load 这几个方法获取路径疑问

1. resolveId
2. load
3. transform

为什么要截取路径 (即substr(1))，是有什么特殊情况？我创建了一个 monorepo 项目，发现会有bug，目录结构如下：

lerna-vite-test
├── docs ------------------------------ vite 项目
│ ├── index.html
│ ├── package.json
│ ├── public
│ │ └── favicon.ico
│ ├── README.md
│ ├── src
│ │ ├── App.tsx --------------------- 在这里引入了 packages 目录下的文件
│ │ ├── assets
│ │ ├── components
│ │ ├── main.ts
│ │ └── shims-vue.d.ts
│ ├── tsconfig.json
│ ├── vite.config.ts
│ └── yarn.lock
├── lerna.json
├── package.json
├── packages ------------------------ 存放 md 项目位置
│ └── button
│ ├── package.json
│ └── src
└── yarn.lock

调试过后发现是路径有误：

1. 原本的路径是 D:/XXX,
2. 经过 substr 后变成 :/XXX，少了 盘符D
3. 拼接后这个路径肯定是有问题的 (path.join(config.root, id.substr(1))

复现 repo: https://github.com/yeojongki/lerna-vite-docs-issue
注：我的环境是 windows

我的解决方法：将 resolveId、transform、load 这几个方法获取路径相关地方不用 substr 拼接，使用原路径即可

提示highlight版本问题，以及高亮颜色有点问题

提示高亮版本问题

Deprecated as of 10.7.0. highlight(lang, code, ...args) has been deprecated.
Deprecated as of 10.7.0. Please use highlight(code, options) instead.
highlightjs/highlight.js#2277

还有高亮颜色，，

可以增加配置去掉表头更改hash的选项么？

这个会影响hash值，如果使用的路由模式是hash模式，那么就会打乱路由的渲染。
这个问题困扰了我很长时间。
大佬可否解决呢？

wrapperComponent无法取得frontmatter

请问使用preview后，unplugin-vue-markdown设定的wrapperComponent就无法取得frontmatter，markdown-it-table-of-contents的[toc]也没有作用，是我哪里用错了吗？

是否可以升级一下@vitejs/plugin-vue至2.x

• 能否把 "@vitejs/plugin-vue": "^1.1.5" 升级到 2x 版本

vite.config.ts导入MarkdownPreview报错问题

项目相关依赖：

build 错误

我知道应该是我的问题，但是我实在是一下子没找到问题所在，请教一下

pnpm build 失败，这个线上也不好demo，放一下仓库吧 🤣
仓库地址：https://github.com/liting-yes/css.git

Cannot find module 'E:\Code\VS Code\blog\vite-blog\node_modules\vite-plugin-md-preview\dist\index.mjs

failed to load config from E:\Code\VS Code\blog\vite-blog\vite.config.ts
error when starting dev server:
Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'E:\Code\VS Code\blog\vite-blog\node_modules\vite-plugin-md-preview\dist\index.mjs' imported from E:\Code\VS Code\blog\vite-blog\vite.config.ts.js
Did you mean to import [email protected][email protected]/node_modules/vite-plugin-md-preview/dist/index.js?
at new NodeError (node:internal/errors:371:5)
at finalizeResolution (node:internal/modules/esm/resolve:418:11)
at moduleResolve (node:internal/modules/esm/resolve:983:10)
at defaultResolve (node:internal/modules/esm/resolve:1080:11)
at ESMLoader.resolve (node:internal/modules/esm/loader:530:30)
at ESMLoader.getModuleJob (node:internal/modules/esm/loader:251:18)
at ModuleWrap. (node:internal/modules/esm/module_job:79:40)
at link (node:internal/modules/esm/module_job:78:36)

使用"vite-plugin-md": "^0.20.2"vue组件并没有被解析出来

使用vite-plugin-md 0.13后，又会面临路径问题#34

still not work in windows

When I use Windows, the vue file displays 404, but I run normally on wsl2. I guess it may be a path problem again

ts in js file in build mode

markdownToVue.js

const toggleCode = (index) => {
          const id = '${resolver_1.VUEDOC_DEMO_PREFIX}' + index
          if (state[id+'Height'] === 0) {
//this line
            state[id+'Height'] = refs[index].value?.offsetHeight || 0
          } else {
            state[id+'Height'] = 0
          }
        }

运行playground\vite代码，解析preview代码块失败

运行playground\vite代码，提示"Failed to load url /src/index.md.DemoBlockI0.vue (resolved id: /src/index.md.DemoBlockI0.vue) in D:/xxl/study/vite-plugin-markdown-preview-main/playground/vite/src/index.md. Does the file exist?"

以下是所有依赖项
"devDependencies": { "@vitejs/plugin-vue": "^4.0.0", "@vitejs/plugin-vue-jsx": "^3.0.0", "vite-plugin-markdown-preview": "^1.0.3", "vite-plugin-vue-markdown": "^0.22.2", "markdown-it-shiki": "^0.7.2" }, "pnpm": { "peerDependencyRules": { "ignoreMissing": [ "vite" ] } }

代码块样式丢失

Broken scoped styles

Some components scoped styles seems broken after plugin inclusion (without options and without use it) :

Before plugin inclusion :

.d-row[data-v-1fea0806],.d-row[data-v-1fea0806-s] {
...
}

After plugin inclusion (hash is added after each selectors) :

.d-row[data-v-1fea0806][data-v-1fea0806],.d-row[data-v-1fea0806-s][data-v-1fea0806] {
...
}

Style in vue file :

<style scoped lang="scss">
.d-row, :slotted(.d-row){
...
}
</style>

The simple fact of commenting or uncommenting the plugin in the configuration causes the bug or not.