Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/xinlei3166/vitepress-theme-demoblock

一个基于 Vitepress 的主题插件,它可以帮助你在编写文档的时候增加 Vue 示例。
https://github.com/xinlei3166/vitepress-theme-demoblock

Last synced: 2 months ago
JSON representation

一个基于 Vitepress 的主题插件,它可以帮助你在编写文档的时候增加 Vue 示例。

Lists

README

        

# vitepress-theme-demoblock

> 这是 3.x 版本的文档,已经采用 [TypeScript](https://www.typescriptlang.org/docs/) 和 [ESM](https://www.ecma-international.org/publications-and-standards/standards/ecma-262/) 规范重写,2.x 版本文档请看[v2文档](v2.md),1.x 版本文档请看[v1文档](v1.md)。

## 简介

`vitepress-theme-demoblock` 是一个基于 `Vitepress` 的主题插件,它可以帮助你在编写文档的时候增加 `Vue` 示例,它的诞生初衷是为了降低编写组件文档时增加一些相关示例的难度。

使用 `Vitepress` 编写组件示例有以下不足之处:
* 1.组件示例和示例代码本质上一样,却需要写两遍。
* 2.`Vitepress` 无法渲染 `Markdown` 中的代码块。

[查看Demo](https://xinlei3166.github.io/vitepress-demo/)

## 提示
由于 `Vitepress` 版本更新频繁,目前支持版本为 `1.0.1`。

`Vue` 支持版本为 `3.4.21`。

## 安装

```bash
npm install -D vitepress-theme-demoblock
yarn add -D vitepress-theme-demoblock
pnpm add -D vitepress-theme-demoblock
```

## 快速上手

`.vitepress/config.js` 文件中使用 `demoblockPlugin` 和 `demoblockVitePlugin` 插件

import { demoblockPlugin, demoblockVitePlugin } from 'vitepress-theme-demoblock'

```js
markdown: {
config: (md) => {
md.use(demoblockPlugin)
}
},
vite: {
plugins: [demoblockVitePlugin()]
}
```

`.vitepress/theme/index.js` 中使用 `vitepress-theme-demoblock` 主题,并注册组件(包含主题中默认的组件)。

```js
import DefaultTheme from 'vitepress/theme'
import 'vitepress-theme-demoblock/dist/theme/styles/index.css'
import { useComponents } from './useComponents'

export default {
...DefaultTheme,
enhanceApp(ctx) {
DefaultTheme.enhanceApp(ctx)
useComponents(ctx.app)
}
}
```

`package.json` 配置命令 `scripts`,`vitepress-rc` 用来注册组件(`--docsDir` 指定docs目录,`--componentsDir` 指定组件注册目录),
如果 `.vitepress` 目录和 `package.json` 同级,--docsDir 设置为 `.`。

```json
"scripts": {
"docs:dev": "yarn run register:components && vitepress dev docs",
"docs:build": "yarn run register:components && vitepress build docs",
"docs:serve": "vitepress serve docs",
"register:components": "vitepress-rc"
}
```

## 更多用法

`.md` 文件中 使用 `style` 和 `script`,参考下面例子:

```markdown
# code snippet ...

body { color: red; }

console.log('vitepress-theme-demoblock setup')

console.log('vitepress-theme-demoblock')

```

## 从 v2 迁移
`v3` 在使用插件时需要使用一个 `Vite` 插件。
```js
vite: {
plugins: [demoblockVitePlugin()]
}
```

`v3` 不支持 `:::demo` 后面的描述。
```js
v2 :::demo 使用 `type`、`plain`、`round` 和 `circle` 属性来定义 Button 的样式。
v3 :::demo
```

因使用了 `Vite` 插件,`Vue` 组件经过 `@vitejs/plugin-vue-jsx` 插件编译, 很多用法已经支持,
例如:setup、jsx、tsx、css v-bind 等等。插件之前的一些属性和方法都已删除,目前只保留了 `customClass` 属性。

## 多语言

`.vitepress/config.js` 文件中增加 `demoblock` 字段来支持多语言 (默认中文)

```js
themeConfig: {
// demoblock locales
demoblock: {
'root': {
'view-source': 'View source',
'hide-source': 'Hide source',
'edit-in-editor': 'Edit in Playground',
'edit-on-github': 'Edit on GitHub',
'copy-code': 'Copy code',
'copy-success': 'Copy success',
'copy-error': 'Copy error',
},
'zh': {
'view-source': '查看源代码',
'hide-source': '隐藏源代码',
'edit-in-editor': '在 Playground 中编辑',
'edit-on-github': '在 Github 中编辑',
'copy-code': '复制代码',
'copy-success': '复制成功',
'copy-error': '复制失败'
}
}
}
```

## 自定义主题

通过配置 `customClass` 类名称,自定义 `demoblock` 样式
```js
markdown: {
config: (md) => {
md.use(demoblockPlugin, {
customClass: 'demoblock-custom'
})
}
}
```

通过重写 `css-variables`,自定义 `demoblock` 样式

```css
:root {
--demoblock-border: var(--vp-c-divider);
--demoblock-control: #909399;
--demoblock-control-bg: var(--vp-c-bg);
}

html.dark {
--demoblock-control: #A3A6AD;
}
```

配置主题色
```css
:root {
--vp-c-brand-1: hsl(237, 100%, 70%);
--vp-c-brand-2: hsl(237, 100%, 73%);
--vp-c-brand-3: hsl(237, 100%, 70%);
--vp-c-brand-soft: hsl(237, 100%, 70%, 14%);
}
```

## 使用第三方组件库

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

在 `.vitepress/theme/index.js` 文件中加入以下代码:
```js
import DefaultTheme from 'vitepress/theme'
import 'element-plus/dist/index.css'
// import ElementPlus from 'element-plus'
// import cn from 'element-plus/lib/locale/lang/zh-cn'

export default {
...DefaultTheme,
enhanceApp(ctx) {
DefaultTheme.enhanceApp(ctx)
// ctx.app.use(ElementPlus, { locale: cn })
}
}
```

使用的时候,导入 `element-plus` 组件即可:
```vue


{{ title }}

点击

import { ref } from 'vue'
import { ElMessage, ElButton } from 'element-plus'

const title = ref('vitepress-theme-demoblock')

const onClick = () => {
ElMessage('消息')
}

```

也可以安装 [unplugin-auto-import](https://github.com/antfu/unplugin-auto-import) 和 [unplugin-vue-components](https://github.com/antfu/unplugin-vue-components) ,配合 `Vite` 实现自动导入。

## 感谢

参考:[element-ui](https://github.com/ElemeFE/element/tree/dev/examples),
[element-plus](https://github.com/element-plus/element-plus/tree/dev/docs),
[vite-plugin-markdown-preview](https://github.com/JasKang/vite-plugin-markdown-preview/blob/main/packages/vite-plugin-markdown-preview/),
[nova-next](https://github.com/em2046/nova-next/blob/master/build/tasks/register-components.ts)