VitePress基础教程

VitePress是一个静态站点生成器(SSG)，专为构建快速、以内容为中心的站点而设计。简而言之，VitePress获取用Markdown编写的内容，对其应用主题，并生成可以轻松部署到任何地方的静态HTML页面。

以下是根据我个人情况去安装使用的介绍步骤，如需更多内容，请前往VitePress官方中文文档。

安装

前置要求

1、nodejs18及以上版本。

到官网下载安装好后使用npm -v查看版本号时出现了以下错误：

PS C:\Users\Administrator> npm -v
npm : 无法加载文件 D:\AAown\AAinstall\node-v22\npm.ps1，因为在此系统上禁止运行脚本。有关详细信息，请参阅 https:/go.microsoft.com/fwlink/?LinkID=135170 中的 about_Execution_Policies。
所在位置 行:1 字符: 1
+ npm -v
+ ~~~
    + CategoryInfo          : SecurityError: (:) []，PSSecurityException
    + FullyQualifiedErrorId : UnauthorizedAccess

这个错误是由于PowerShell执行策略限制了脚本的运行。默认情况下，Windows会禁止执行来自互联网或不受信任来源的脚本。

解决： 修改执行策略，为了允许脚本运行，可以设置执行策略为RemoteSigned或Unrestricted。选择RemoteSigned比较安全，它允许运行本地脚本和签名的远程脚本。

PS C:\Users\Administrator> Get-ExecutionPolicy
Restricted
PS C:\Users\Administrator> Set-ExecutionPolicy RemoteSigned
PS C:\Users\Administrator> npm -v
10.9.0

执行策略	描述
Restricted	默认设置，不允许任何脚本运行。只能执行单个命令
AllSigned	只允许运行由可信发布者签名的脚本和配置文件
RemoteSigned	允许运行本地脚本，但从互联网下载的脚本必须由可信发布者签名
Unrestricted	允许所有脚本运行。下载的脚本在运行之前会提示用户是否愿意运行
Bypass	完全绕过执行策略检查，允许所有脚本运行，不显示任何警告或提示
Undefined	没有为当前作用域设置执行策略，默认执行策略为Restricted

2、通过命令行界面(CLI)访问VitePress的终端。
3、支持markdown的编辑器，如vscode等。
4、Git的支持。

安装和初始化

使用npm安装VitePress，需要先进入到你想要安装的目录中。

PS C:\Users\Administrator> cd E:\AAvscode\ADvitepress
PS E:\AAvscode\ADVitePress> ls
PS E:\AAvscode\ADVitePress>
PS E:\AAvscode\ADVitePress> npm add -D vitepress

added 126 packages in 34s

39 packages are looking for funding
  run `npm fund` for details
npm notice
npm notice New major version of npm available! 10.9.0 -> 11.0.0
npm notice Changelog: https://github.com/npm/cli/releases/tag/v11.0.0
npm notice To update run: npm install -g npm@11.0.0
npm notice
PS E:\AAvscode\ADVitePress> ls


    目录: E:\AAvscode\ADVitePress


Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d-----        2024/12/19     17:14                node_modules
-a----        2024/12/19     17:14          85768 package-lock.json
-a----        2024/12/19     17:14             57 package.json


PS E:\AAvscode\ADVitePress>

VitePress附带一个命令行设置向导，可以帮助你构建一个基本项目。

PS E:\AAvscode\ADVitePress> npx vitepress init

┌  Welcome to VitePress!
│
◇  Where should VitePress initialize the config?
│  ./docs
│
◇  Site title:
│  docs
│
◇  Site description:
│  docs运维文档
│
◇  Theme:
│  Default Theme + Customization
│
◇  Use TypeScript for config and theme files?
│  Yes
│
◇  Add VitePress npm scripts to package.json?
│  Yes
│
└  Done! Now run npm run docs:dev and start writing.

PS E:\AAvscode\ADVitePress>

目录结构

此时目录结构如下：

.
├─ docs
│  ├─ .vitepress
│  │  └─ config.mst
│  ├─ api-examples.md
│  ├─ markdown-examples.md
│  └─ index.md
└─ package.json

docs目录作为vitepress站点的项目根目录。.vitepress目录是vitepress配置文件、开发服务器缓存、构建输出和可选主题自定义代码的位置。

在docs目录下创建一个public的公共目录，这个目录存放一些公共的文件，比如图片，以后需要在网页中链接图片可以把public作为根目录，比如public下有一个名为yunwei.png的一张图片，链接到该图片的方法为/yunwei.png。

项目调试

启动服务

PS E:\AAvscode\ADVitePress> npm run docs:dev

1、作用： 启动本地开发服务器，用于开发和调试文档。

2、详细说明
1）该命令会启动一个开发服务器，并监听文件变化。
2）当你修改Markdown文件或配置文件时，开发服务器会自动重新构建并刷新页面。
3）默认情况下，开发服务器会运行在http://localhost:5173（或其他可用端口）。

3、适用场景： 在开发文档时使用，可以实时查看修改效果。

构建站点

PS E:\AAvscode\ADVitePress> npm run docs:build

1、作用： 构建生产环境的静态站点。

2、详细说明
1）该命令会将Markdown文件、Vue组件和静态资源打包成静态HTML、CSS和JavaScript文件。
2）构建结果默认输出到.vitepress/dist目录。
3）构建后的文件可以部署到任何静态站点托管服务（如GitHub Pages、Netlify、Vercel等）。

3、适用场景： 在发布文档之前使用，生成最终的生产环境文件。

预览站点

PS E:\AAvscode\ADVitePress> npm run docs:preview

1、作用： 预览构建后的静态站点。

2、详细说明
1）该命令会启动一个本地服务器，用于预览docs:build生成的静态站点。
2）默认情况下，预览服务器会运行在http://localhost:4173（或其他可用端口）。
3）通过预览，可以确保构建结果与开发环境一致。

3、适用场景： 在部署之前，检查构建结果是否符合预期。

导航栏

// .vitepress/config.mts

export default defineConfig({

  //其他代码

  themeConfig: {

    nav: [
      { text: '运维文档',
        link: '/yunwei-docs.html',
      },
      { text: '关于',
        link: '/about.html',
       },
    ],

    //其他代码

  }

})

侧边栏

// .vitepress/config.mts

export default defineConfig({

  //其他代码

  themeConfig: {

    sidebar: [
      {
        text: 'Windows运维文档',
        collapsed: false,
        items: [
          { text: 'Windows使用及问题解决', link: '/win-maintain/win-easyuse.html' },
          { text: '常用快捷键和快捷命令', link: '/win-maintain/key-cmd.html' },
          ...
        ]

        text: '零散文档',
        collapsed: false,
        items: [
          { text: 'Git基础教程', link: '/varied-file/git-base.html' },
          { text: 'Docker基础教程', link: '/varied-file/docker-base.html' },
          ...
        ]

        ...

      }
    ]

    //其他代码

  }

})

页脚

// .vitepress/config.mts

export default defineConfig({

  //其他代码

  themeConfig: {

    footer: 
    {
      message: '基于 VitePress 创建',
      copyright: '版权所有 © 2024-至今 典典诚运维'
    },

    //其他代码

  }

})

添加logo图标

// .vitepress/config.mts

export default defineConfig({

  //其他代码

  themeConfig: {

    logo: '/pt-public/dnc32.png',

    //其他代码

  }

})

添加标签页图标

// .vitepress/config.mts

export default defineConfig({

  //其他代码

  head: [
    [
      'link',
      {
        rel: 'icon',
        href: '/pt-public/dnc32.ico',
      },
    ],
  ],

})

添加搜索功能

// .vitepress/config.mts

export default defineConfig({

  //其他代码

  themeConfig: {

    search: {
      provider: 'local',
      options: {
        miniSearch: {
          options: {
            /* ... */
          },
          searchOptions: {
            /* ... */
          },
        },
        translations: {
          button: {
            buttonText: "搜索文档",
            buttonAriaLabel: "搜索文档",
          },
          modal: {
            noResultsText: "没有找到结果",
            resetButtonTitle: "清除搜索条件",
            footer: {
              selectText: "选择",
              navigateText: "切换",
              closeText: "关闭",
            },
          },
        },
      },
    },

    //其他代码

  }

})

图片浏览功能

PS E:\AAvscode\ADvitepress> npm install medium-zoom

// .vitepress/theme/index.ts

import { onMounted, watch, nextTick } from 'vue'
import { useRoute } from 'vitepress'
import mediumZoom from 'medium-zoom'

export default {

  //其他内容

  ...DefaultTheme,

  setup() {
    const route = useRoute()
    const initZoom = () => {
      mediumZoom('[data-zoomable]', { background: 'var(--vp-c-bg)' })
      mediumZoom('.main img', { background: 'var(--vp-c-bg)' })
    }
    onMounted(() => {
      initZoom()
    })
    watch(
      () => route.path,
      () => nextTick(() => initZoom())
    )
  },

} satisfies Theme

/* .vitepress/theme/index.css */
/* 图片放大 */

.medium-zoom-overlay {
  z-index: 1000;
  cursor: pointer; /* 可选：添加鼠标悬停效果 */
  transition: transform 0.3s ease-in-out; /* 可选：平滑过渡 */
}

.medium-zoom-image--opened {
  z-index: 1001;
}

代码块中显示行号

// .vitepress/config.mts

export default defineConfig({

  //其他代码

  markdown: {
    lineNumbers: true,
  },

})

外观模式(浅/深色)

// .vitepress/config.mts

export default defineConfig({

  //其他代码

  appearance: true, // 启用模式切换
  appearance: false, // 禁用模式切换
  appearance: 'dark', // 强制深色模式
  appearance: 'force-dark', // 强制深色模式并禁用切换
  appearance: 'force-light', // 强制浅色模式并禁用切换

})

更多其他配置

// .vitepress/config.mts

export default defineConfig({

  //其他代码

  themeConfig: {

    docFooter: {
      prev: "上一页",
      next: "下一页"
    },

    //文档右侧导航栏显示的标题为二级到三级标题
    outline: {
      level: [2, 3],
      label: "页面导航"
    },
    
    lightModeSwitchTitle: "切换到浅色模式",
    darkModeSwitchTitle: "切换到深色模式",

    //其他代码

  }

})

index.md

---
# https://vitepress.dev/reference/default-theme-home-page
layout: home

hero:
  name: "典典诚运维"
  image:
    src: /pt-public/dnc320.png
    alt: 典典诚运维
  text: "运维文档、配置指南，常见问题及解决方案"
  tagline: 电脑、软硬件、打印机、投影仪、网络设备等
  actions:
    - theme: brand
      text: 直达所有文档
      link: /win-maintain/win-easyuse.html
      target: _blank
    - theme: alt
      text: 关于
      link: /about.html
      target: _blank

features:
  - icon: 
      src: '/pt-public/user.svg'
    title: 用户支持
    details: 远程支持，现场支持。了解用户需求和问题，处理用户的技术问题，提供及时的支持和解决方案。
    link: '/'
    
  - icon: 
      src: '/pt-public/system.svg'
    title: 操作系统
    details: 对Windows10/11、Deepin、UOS等操作系统的安装、配置与优化。快速诊断并修复操作系统故障等。
    link: '/'

  - icon: 
      src: '/pt-public/printer.svg'
    title: 外设管理
    details: 打印机、投影仪等外设的驱动安装、连接配置。解决设备无法连接、投影不显示等问题，并定期更换耗材。
    link: '/'

  - icon: 
      src: '/pt-public/switch.svg'
    title: 网络设备
    details: 路由器与交换机配置，解决IP冲突、网络不通等常见网络问题。确保网络稳定运行，提升访问速度和可靠性。
    link: '/'
---

主页图片背景渐变

/* .vitepress/theme/index.css */
/* index主页中右侧图片背景颜色渐变 */

:root {
  --vp-home-hero-name-color: transparent;
  --vp-home-hero-name-background: -webkit-linear-gradient(120deg, #bd34fe, #41d1ff);

  --vp-home-hero-image-background-image: linear-gradient( 120deg, #bd34fe 50%, #41d1ff 100%);
  --vp-home-hero-image-filter: blur(150px);
}