ELMEC DOCS

Theme

vitepress 总结 ​

前言 ​

本文仅对使用过程中出现的问题进行总结，VitePress 使用方法请参考 VitePress 官方文档 和 快速上手中文教程。

安装向导 ​

建议选择在./docs中搭建VitePress项目，生成的文件结构应该是这样的

sh
┌  Welcome to VitePress!
│
◇  Where should VitePress initialize the config?
│  ./docs
│
◇  Where should VitePress look for your markdown files?
│  ./docs
│
◇  Site title:
│  My Awesome Project
│
◇  Site description:
│  A VitePress Site
│
◇  Theme:
│  Default Theme
│
◇  Use TypeScript for config and theme files?
│  Yes
│
◇  Add VitePress npm scripts to package.json?
│  Yes
│
◇  Add a prefix for VitePress npm scripts?
│  Yes
│
◇  Prefix for VitePress npm scripts:
│  docs
│
└  Done! Now run pnpm run docs:dev and start writing.

Git忽略项 ​

添加.gitignore文件，主要用于上传到gitee/github时，忽略这些文件不上传， 在cmd中运行以下命令：

sh
echo node_modules >> .gitignore
echo cache >> .gitignore
echo dist >> .gitignore

文件结构 ​

请按以下文件结构组织

sh
.
├─ docs/
│  ├─ .vitepress
│  │  ├─ config.mts         # 配置文件
│  │  ├─ theme/             # 主题相关
│  │  │  ├─ index.ts        # 加载css、js、页面等设定
│  │  │  └─ style/          # 主题样式目录
│  │  │     ├─ index.css    # 只导入css样式文件
│  │  │     ├─ var.css      # css变量相关定义(添加到index.css中)
│  │  │     ├─ *.css        # 其它css样式文件(添加到index.css中)
│  │  │     └─ code.css     # 代码块样式定义(添加到index.css中)
│  │  ├─ config/            # 分拆config.mts文件
│  │  │  ├─ markdown.ts     # Markdown 配置 (添加到config.mts中)
│  │  │  └─ theme.ts        # 主题配置文件(添加到config.mts中)
│  │  ├─ plugins/           # 插件目录
│  │  └─ utils/             # 工具函数目录
│  ├─ post/                 # 存放md文章目录
│  ├─ public/               # 存放公共静态资源的目录
│  ├─ cache/                # 运行时缓存(不上传Github)
│  ├─ dist/                 # build生成的静态网站(不上传Github)
│  └─ index.md              # 首页md文档
├─ node_modules/            # 依赖包(不上传Github)
├─ package-lock.json        # 项目依赖包配置文件
└─ package.json             # VitePress配置

除了post目录下的子目录和文件外，所有其他文件名都必须是小写

浅色主题, 暗色代码块 ​

  1. markdown 的代码高亮主题强制设为暗色
ts
markdown: {
    // 强制指定一个暗色主题，例如 'vitesse-dark', 'github-dark', 'one-dark-pro'
    theme: "one-dark-pro",
    config: (md) => {
      // 换行：支持单回车换行 (Breaks)
      md.set({ breaks: true });
    }
}
  1. 修改 css 样式
css
:root, .dark {
    /* 代码块背景色 */
    --vp-code-block-bg: var(--slate-800);
    /* 还需修改其他样式变量 */
}

⚠️单回车换行 (Breaks) ​

ts
markdown: {
    // 强制指定一个暗色主题，例如 'vitesse-dark', 'github-dark', 'one-dark-pro'
    theme: "one-dark-pro",
    config: (md) => {
      // 换行：支持单回车换行 (Breaks)
      md.set({ breaks: true });
    }
}

⚠️EdgeOne部署失败 ​

本地build通过，但是部署到EdgeOne时通不过

  1. 查看部署日志
  2. 检查文件夹名和文件名的大小写、特别是md文件的图片资源文件名，因为在windows下不区分大小写，而EdgeOne是区分大小写的。

md文件对应不同字体 ​

  1. 读取文件名或frontmatter中的语言，注入到html的lang属性中
ts
export default {
  extends: DefaultTheme,

    // --- 新增 setup 函数处理字体逻辑 ---
  setup() {
    const { frontmatter, page } = useData()

    const updateLangClass = () => {
      if (typeof window === 'undefined') return
      const htmlEl = document.documentElement
      
      // 逻辑：优先看 frontmatter 里的 lang，
      // 如果没有，则判断文件名是否包含 -jp 或 -ja (对应你的 daq3-manual-jp.md)
      const fmLang = frontmatter.value.lang
      const fileName = page.value.relativePath

      htmlEl.classList.remove('lang-zh', 'lang-ja')

      if (fmLang?.includes('ja') || fmLang?.includes('jp') || fileName.includes('-jp') || fileName.includes('-ja')) {
        htmlEl.classList.add('lang-ja')
        htmlEl.lang = 'ja-JP'
      } else {
        htmlEl.classList.add('lang-zh')
        htmlEl.lang = 'zh-CN'
      }
    }

    onMounted(updateLangClass)
    // 监听路由变化，确保切换页面时字体同步更新
    watch(() => page.value.relativePath, updateLangClass)
  },
} satisfies Theme
  1. 分别对中文和日文设置不同的字体
css
/* 英文或中文字体 */
:root {
    --vp-font-family-base: 'Inter4CJK', -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
    --vp-font-family-mono: 'JetBrains Mono', ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
}

/* 日文字体 */
[lang]:where(:lang(ja)) {
    --vp-font-family-base: 'Inter4CJK', "Hiragino Kaku Gothic ProN", "Meiryo", sans-serif;
    --vp-font-family-mono: 'JetBrains Mono', 'BIZ UDGothic', ui-monospace, monospace;
}

注意：如果css中没有分别定义中日文字体、当字体家庭中有 sans-serif, monospace 这样的字体时，也会根据html的lang属性来选择不同的字体。

上标和下标 ​

VitePress默认不支持上标和下标，需要安装插件。

sh
npm install markdown-it-sup markdown-it-sub

配制上下标插件

ts
import sup from 'markdown-it-sup'
import sub from 'markdown-it-sub'
export default {
  markdown: {
      md.use(sup);
      md.use(sub);
  }
}

Mark ​

VitePress默认不支持mark标记，需要安装插件。
如: ==重要== 娈为 重要

sh
npm install markdown-it-mark

配制mark插件

ts
import mark from 'markdown-it-mark'
export default {
  markdown: {
      md.use(mark);
  }
}

如果不安装插件，也可以用<mark>标签实现。
如: <mark>重要</mark> 娈为 重要

数学方程 ​

VitePress默认不支持数学方程，需要安装mathjax插插件。

sh
npm add -D markdown-it-mathjax3@^4

配制mathjax插件

ts
import mathjax3 from 'markdown-it-mathjax3'
export default {
  markdown: {
    math: true
  }
}

mermaid ​

VitePress默认不支持mermaid图表，需要安装mermaid相关插件。

由于VitePress 2.0以上版本不支持安装VitePress-plugin-mermaid插件，如要对应先安装mermaid插件，再自己写代码实现

详细代码连接
https://github.com/vuejs/vitepress/discussions/4999

END

ELMEC Document Center

Copyright © 2026