不敲一行代码！助你快速搭建属于自己的官网博客！-VitePress保姆级教程

前言

我们在阅读官方文档时，经常看到一些项目的文档非常简约精美，并且布局高度相似，其实这些官网是基于vitepress搭建，例如：

Vite官方文档
在这里插入图片描述

Vue-Use
在这里插入图片描述

SnowAdmin
在这里插入图片描述

这些官网都是基于vitepress搭建，virepress给我们提供了非常多的配置，我们只需要按照配置修改即可实现上图中的效果，并且在virepress我们不需要手写代码，只需要使用Markdown即可轻松构建精美的文档网站，就像你平时写Markdown文档一样，专注于文档编写即可。

项目搭建

开始

pnpm add -D vitepress
或
npm add -D vitepress

安装向导

VitePress 附带一个命令行设置向导，可以帮助你构建一个基本项目。安装后，通过运行以下命令启动向导：

pnpm vitepress init
或
npx vitepress init

此时终端会向你提问，这个引导是项目的初始化设置，例如：项目名称、项目描述等

┌  Welcome to VitePress!
│
◇  Where should VitePress initialize the config?
│  ./docs
│
◇  Site title:
│  My Awesome Project
│
◇  Site description:
│  A VitePress Site
│
◆  Theme:
│  ● Default Theme (Out of the box, good-looking docs)
│  ○ Default Theme + Customization
│  ○ Custom Theme
└

在这里插入图片描述

回答完后项目即搭建完成，下面是项目结构

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

先安装依赖

    pnpm i
    或
    npm i

运行pnpm run docs:dev即可预览项目
在这里插入图片描述

首页修改

在vitepress中，首页配置在docs文件夹下的index.md文件
在这里插入图片描述

接下来我们对首页进修改，下面箭头标注的就是在index.md中对应的修改位置，修改为下面的效果：
在这里插入图片描述

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

    hero:
      name: "SnowAdmin"
      text: "清新优雅的中后台模版"
      tagline: 专注、免费、开源、维护、解疑
      image:
        src: /snow.svg
        alt: SnowAdmin
      actions:
        - theme: brand
          text: 开始
          link: /api-examples
        - theme: alt
          text: 在线预览
          target: _blank
          link: 你的链接
        - theme: alt
          text: 在Gitee上查看
          target: _blank
          link: 你的链接

    features:
      - icon: 📒
        title: 代码全注释
        details: Vue3,Vite5,TypeScript 和 Arco-Design，代码方法全部注释，方便理解、学习。
      - icon: ❄
        title: 清晰的项目结构
        details: 采用 pnpm，结构清晰优雅，易于维护。代码规范性极高。
      - icon: 🎉
        title: 解疑问
        details: 加群解答探讨开发遇到的各种问题，1群：建设中。
    ---

上面的代码直接赋值粘贴到你的index.md中即可预览效果

在上面的代码中，image为首页的图片配置，src就是图片指引位置，对应public下的静态资源文件
在这里插入图片描述

项目配置

在vitepress中，基本项目配置是基于.viewpress/config.mts，例如首页的顶部导航位置、首页右侧的按钮、在阅读中的上一页、下一页、页面的footer等一系列配置，都是基于config.mts文件。

在这里插入图片描述

下面我们来对项目全局按钮进行配置
在这里插入图片描述

    import { defineConfig } from "vitepress";

    // .viewpress/config.mts
    export default defineConfig({
      title: "SnowAdmin",
      description: "SnowAdmin官方文档",
      // 项目配置
      themeConfig: {
        logo: "/snow.svg", // 项目的logo
        // 顶部按钮配置
        nav: [
          { text: "指南", link: "/" },
          { text: "配置", link: "/markdown-examples" },
          {
            text: "链接",
            // 内部配置items则该按钮是下拉，link则是跳转链接
            items: [
              {
                text: "在线预览",
                link: "http://101.126.93.137/#/login",
              },
              {
                text: "Gitee仓库",
                link: "https://gitee.com/wang_fan_w/SnowAdmin",
              },
              {
                text: "GitHub仓库",
                link: "https://github.com/WANG-Fan0912/SnowAdmin",
              },
            ],
          },
        ],

        sidebar: [
          {
            text: "Examples",
            items: [
              { text: "Markdown Examples", link: "/markdown-examples" },
              { text: "Runtime API Examples", link: "/api-examples" },
            ],
          },
        ],
        // 顶部最右侧github图标
        socialLinks: [
          { icon: "github", link: "https://github.com/vuejs/vitepress" },
        ],
        // 项目首页的footer
        footer: {
          message: "基于 MIT 许可发布",
          copyright: "版权所有 © 2024-2029 兔子先森",
        },
      },
    });

上面的代码直接赋值粘贴到你的config.mts中即可预览效果
虽然我们在项目中配置了logo，但是浏览器标签页上的logo依旧没有变化，此时需要配置head
在这里插入图片描述

    export default defineConfig({
      title: "SnowAdmin",
      description: "SnowAdmin官方文档",
      head: [["link", { rel: "icon", href: "/snow.svg" }]], // 浏览器标签页logo
      // 省略其它配置......
    });

在这里插入图片描述