npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

vuepress-plugin-demoblock-plus

v2.0.4

Published

vuepress plugin for demoblock

Downloads

602

Readme

vuepress-plugin-demoblock-plus

这是2.x版本的文档,已经采用TypeScript和ESM规范重写,如果使用1.x版本请看v1文档

简介

vuepress-plugin-demoblock-plus 是一个基于 Vuepress 2.x 的插件,它可以帮助你在编写文档的时候增加 Vue 示例,它的诞生初衷是为了降低编写组件文档时增加一些相关示例的难度。

使用 Vuepress 编写组件示例有以下不足之处:

  • 1.组件示例和示例代码本质上一样,却需要写两遍。
  • 2.Vuepress 无法渲染 Markdown 中的 script 和 style 代码块。

vuepress-plugin-demoblock-plus 参考了 Element UI 的文档渲染,实现了和它一样的,可在 Markdown 中直接编写示例的语法。

查看Demo

提示

由于vuepress版本不稳定,目前锁定版本为2.0.0-beta.51。 待vuepress新版本稳定文档更新后,文档和插件会同步修改。

[email protected]版本下setup语法报错,锁定vue版本为3.2.44。

安装

npm install -D vuepress-plugin-demoblock-plus
yarn add -D vuepress-plugin-demoblock-plus
pnpm add -D vuepress-plugin-demoblock-plus

快速上手

.vuepress/config.js文件中使用插件

import { demoblockPlugin } from 'vuepress-plugin-demoblock-plus'

plugins: [demoblockPlugin()]

更多用法

markdown 中的vue代码包含的style内容,会被组合成一个style统一处理,如果需要使用css预处理器,需要提前指定并且手动安装使用的css预处理器。

plugins: [demoblockPlugin({ cssPreprocessor: 'less' })]

自定义style tag name

plugins: [
  demoblockPlugin({
    customStyleTagName: 'style lang="less"' // style标签会解析为<style lang="less"><style>
  })
]

markdown 中的vue代码被编译为了 vue 函数组件,需要把 import 转换为 require,这里可附加一些其他的转换。 vue已经内置做了转换,例如 import { ref } from 'vue' 会被转换为 const { ref } = Vue。 这里编码风格使用的是单引号,如果你使用的是双引号,需自行处理(详见#21)。

plugins: [
  demoblockPlugin({
    scriptImports: ["import * as ElementPlus from 'element-plus'"],
    scriptReplaces: [
      { searchValue: /const ({ defineComponent as _defineComponent }) = Vue/g,
        replaceValue: 'const { defineComponent: _defineComponent } = Vue'
      },
      { searchValue: /import ({.*}) from 'element-plus'/g,
        replaceValue: (s, s1) => `const ${s1} = ElementPlus`
      }
    ]
  })
]

多style和多script支持

为了把markdown中的代码渲染为组件,内部已经使用了script和style。如果想在md文件中使用script可以使用script setup,参考下面例子:

## 多style和多script支持
code snippet ...

<style>
body {
color: red;
}
</style>

<script setup lang="ts">
console.log('script')
</script>

多语言支持(默认是中文)

const locales = {
  '/': {
    'hide-text': 'Hide',
    'show-text': 'Expand',
    'copy-button-text': 'Copy',
    'copy-success-text': 'Copy success'
  },
   '/zh': {
    'hide-text': '隐藏代码',
    'show-text': '显示代码',
    'copy-button-text': '复制代码片段', 
    'copy-success-text': '复制成功'
  }
}

plugins: [demoblockPlugin({ locales })]

自定义主题

支持vuepress darkMode,.vuepress/config.js 文件中配置 darkMode: true

themeConfig: { darkMode: true }

使用 shiki 默认自带的主题代码高亮

plugins: [
  demoblockPlugin({
    theme: 'github-light',
  })
]

使用 shiki css-variables 自定义代码高亮,theme 参数设置为 css-variables

:root {
  --shiki-color-text: #24292f;
  --shiki-color-background: #ffffff;
  --shiki-token-constant: #0550ae;
  --shiki-token-string: #24292f;
  --shiki-token-comment: #6e7781;
  --shiki-token-keyword: #cf222e;
  --shiki-token-parameter: #24292f;
  --shiki-token-function: #8250df;
  --shiki-token-string-expression: #0a3069; // #116329
  --shiki-token-punctuation: #24292f;
  //--shiki-token-link: #000012;
}

html.dark {
  --shiki-color-text: #c9d1d9;
  --shiki-color-background: #0d1117;
  --shiki-token-constant: #79c0ff;
  --shiki-token-string: #a5d6ff;
  --shiki-token-comment: #8b949e;
  --shiki-token-keyword: #ff7b72;
  --shiki-token-parameter: #c9d1d9;
  --shiki-token-function: #d2a8ff;
  --shiki-token-string-expression: #a5d6ff; // #7ee787;
  --shiki-token-punctuation: #c9d1d9;
  //--shiki-token-link: #000012;
}

如果出现类似这个错误 Error: ENOENT: no such file or directory, node_modules/shiki/themes/css-variables.json, 这是因为 shiki css-variables 需要更高版本才能使用,删除 node_modules,重新安装 @vuepress/plugin-shikivuepress-vite

通过配置 customClass 类名称,自定义demoblock样式

plugins: [
  demoblockPlugin({
    customClass: 'demoblock-custom',
  })
]

通过配置暴露的 css-variables,自定义demoblock样式, --code-bg-color 是代码块的背景色,light和dark模式下背景色要区分

:root {
  --code-bg-color: #f9fafb;
  --demoblock-border: var(--c-border);
  --demoblock-control: #d3dce6;
  --demoblock-control-bg: var(--c-bg);
  --demoblock-control-bg-hover: #f9fafc;
  --demoblock-description-bg: var(--c-bg);
}

html.dark {
  --code-bg-color: #282c34;
  --demoblock-border: var(--c-border);
  --demoblock-control: #8b9eb0;
  --demoblock-control-bg: var(--c-bg);
  --demoblock-control-bg-hover: var(--c-bg);
  --demoblock-description-bg: var(--code-bg-color);
}

配置主题色

:root {
  --c-brand: #646cff;
  --c-brand-light: #747bff;
}

使用第三方组件库

这个插件主要是针对自己的组件库来使用的,第三方的组件库直接导入使用即可(例如element-plus)。

在 .vuepress/clientAppEnhance.js 文件中加入以下代码:

import { defineClientAppEnhance } from '@vuepress/client'
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'

export default defineClientAppEnhance(({
  app,
  router,
  siteData,
}) => {
  app.use(ElementPlus)
})

使用的时候,不用导入element组件,直接使用即可:

<template>
  <div class="card-wrap">
    <div class="card">{{ title }}</div>
    <el-button type="primary" @click="onClick">点击</el-button>
  </div>
</template>

<script setup>
import { ref, getCurrentInstance } from 'vue'

const title = ref('vuepress-plugin-demoblock-plus')

const instance = getCurrentInstance()

const onClick = () => {
  instance.appContext.config.globalProperties.$message.success('消息')
}
</script>