VitePress Theme Element Plus1.1.1

Appearance

快速开始 ​

根据下面的步骤操作可快速获得与 Element-plus 文档网站几乎一致的渲染效果。如果有不需要的插件或配置项可自行选择。

安装依赖 ​

bash
pnpm add -D vitepress-theme-element-plus vitepress-better-demo-plugin vitepress-plugin-group-icons markdown-it-container element-plus sass-embedded

如果需要在 TypeScript 项目中获得更完整的提示，可额外安装 @types/markdown-it-container。如果不安装 element-plus 和 sass-embedded 主题无法正常渲染。

创建配置文件 ​

以下片段引用自本文档的配置文件，展示了如何把主题、Markdown 插件和 Vite 行为串联在一起。 可以根据需要在此配置文件的基础上进行删改。

mts
import type { EPThemeConfig } from 'vitepress-theme-element-plus'
import path, { dirname } from 'node:path'
import { fileURLToPath } from 'node:url'
import mdContainer from 'markdown-it-container'
import { defineConfig } from 'vitepress'
import { createDemoContainer } from 'vitepress-better-demo-plugin'
import { groupIconMdPlugin, groupIconVitePlugin } from 'vitepress-plugin-group-icons'
import { mdExternalLinkIcon, mdTableWrapper, mdTag, mdTaskList, mdTooltip } from 'vitepress-theme-element-plus/node'
import pkg from '../package.json'
import { createSeoHead, DEFAULT_DESCRIPTION, enhancePageData, SITE_NAME, SITE_URL } from './seo'

export default defineConfig<EPThemeConfig>({
  lang: 'zh-CN',
  vite: {
    plugins: [
      groupIconVitePlugin(),
    ],
    ssr: {
      noExternal: [
        'vitepress-theme-element-plus',
        'vitepress-better-demo-plugin',
      ],
    },
    optimizeDeps: {
      exclude: ['vitepress-theme-element-plus'],
    },
    build: {
      cssMinify: false,
    },
  },
  // 站点配置
  title: SITE_NAME,
  titleTemplate: ':title · Element Plus 风格 VitePress 主题',
  description: DEFAULT_DESCRIPTION,
  cleanUrls: true,
  lastUpdated: true,
  head: [
    ['link', { rel: 'icon', href: '/favicon.svg' }],
    ['meta', { name: 'theme-color', content: '#3b82f6' }],
  ],
  appearance: true,
  transformPageData: enhancePageData,
  transformHead({ pageData }) {
    return createSeoHead(pageData)
  },
  // Markdown 配置
  markdown: {
    math: true,
    theme: {
      light: 'github-light',
      dark: 'github-dark',
    },
    config(md) {
      md.use(groupIconMdPlugin)
      md.use(mdExternalLinkIcon)
      md.use(mdTag)
      md.use(mdTooltip)
      md.use(mdTableWrapper)
      md.use(mdTaskList, {
        disabled: false,
      })
      md.use(mdContainer, 'demo', createDemoContainer(md, {
        demoDir: path.resolve(
          dirname(fileURLToPath(import.meta.url)),
          '../demo',
        ),
        autoImportWrapper: false,
      }))
    },
  },
  // 全局主题配置
  themeConfig: {
    // Logo 配置
    logo: '/logo.svg',

    // 搜索配置
    search: {
      provider: 'local',
    },
    version: pkg.version,
    siteTitle: SITE_NAME,
    sidebar: [
      {
        text: '指南',
        items: [
          { text: '介绍', link: '/guide/introduction' },
          { text: '快速开始', link: '/guide/quick-start' },
          { text: 'Vitepress 插件', link: '/guide/vitepress-plugin' },
          { text: 'Markdown 插件', link: '/guide/md-plugin' },
          { text: '修改配色', link: '/guide/theme' },
          { text: '渲染测试页', link: '/guide/demo-page' },
        ],
      },
    ],
    externalLinkIcon: true,
    // 社交链接
    socialLinks: [
      { icon: 'github', link: 'https://github.com/hezhengxu2018/vitepress-theme-element-plus' },
    ],

    // Footer 配置
    footer: {
      copyright: 'Release under MIT License',
      blogroll: [
        {
          title: '链接',
          children: [
            { text: 'GitHub', link: 'https://github.com/hezhengxu2018' },
            { text: 'Element Plus', link: 'https://element-plus.org/' },
            { text: 'VitePress', link: 'https://vitepress.vuejs.org/' },
            { text: 'Vitepress Better Demo Plugin', link: 'https://vitepress-better-demo-plugin.pages.dev/' },
          ],
        },
        {
          title: '参考',
          children: [
            { text: 'Dux Docs', link: 'https://duxweb.github.io/vitepress-theme/' },
            { text: 'VitePress Theme Mild', link: 'https://theme.hacxy.cn/' },
            { text: 'Vitepress Theme Teek', link: 'https://vp.teek.top/' },
            { text: 'VitePress Carbon', link: 'https://carbon.breno.tech/' },
          ],
        },
      ],
    },
    nav: [
      { text: '首页', link: '/' },
      { text: '指南', link: '/guide/introduction', activeMatch: '/guide/' },
      { text: '官方配置项', link: 'https://vitepress.dev/zh/reference/site-config' },
    ],
  },
  sitemap: {
    hostname: SITE_URL,
  },
})

注册主题入口 ​

在 .vitepress/theme/index.ts 中复用主题默认导出，并把 demo 包裹组件和图标样式挂入 VitePress：

ts
import {
  VitepressEpDemoBox,
  VitepressEpDemoPlaceholder,
} from 'vitepress-better-demo-plugin/theme/element-plus'
import Theme from 'vitepress-theme-element-plus'
import 'virtual:group-icons.css'

export default {
  ...Theme,
  enhanceApp({ app }) {
    app.component('VitepressDemoBox', VitepressEpDemoBox)
    app.component('VitepressDemoPlaceholder', VitepressEpDemoPlaceholder)
  },
} as typeof Theme