正心全栈编程-文档站

Appearance

VitePress 系列教程：VitePress 基本配置 #3 ​

docs 目录下的 .vitepress 目录是专门用来存放配置文件的，在里面新建一个 config.js 配置文件，结构如下

.
├─ docs
│  ├─ .vitepress
│  │  └─ config.js
│  └─ index.md
└─ package.json

config.js 导出一个 js 对象，用来配置项目当中的一些信息。

js
export default {
  title: "zhengxin", // 站点标题
  description: "正心的全栈编程笔记", // mate 标签 description，多用于搜索引擎抓取摘要
};

导航栏 ​

右侧导航 ​

可以在 themeConfig.nav 配置右侧导航，并且点击可以跳转我们指定页面。

js
export default {
  title: "zhengxin", // 站点标题
  description: "正心的全栈编程笔记", // mate 标签 description，多用于搜索引擎抓取摘要
  themeConfig: {
    // 主题配置
    // siteTitle: "正心全栈编程", // 站点首页标题
    logo: "logo.svg", // 站点 logo
    nav: [
      { text: "博客", link: "/articles/" },
      { text: "Python", link: "/python/" },
      { text: "前端", link: "/frontend/" },
      { text: "gitee", link: "https://gitee.com/zhengxinonly" }, // 外链
    ], // 右上角头部导航栏
  },
};

同时在 docs 下新建 articles/index.md 和 python/index.md

此时我们页面即可展示 nva 并且支持了跳转本地 markdown 文件以及外部链接

我们还可以这样嵌套配置，使得导航栏出现下拉选项

js
// 项目的配置文件目录
export default {
  themeConfig: {
    logo: "logo.svg", // 站点 logo
    nav: [
      { text: "博客", link: "/articles/组件库环境搭建" },
      { text: "Python", link: "/python/" },
      { text: "前端", link: "/frontend/" },
      { text: "gitee", link: "https://gitee.com/zhengxinonly" }, // 外链
      {
        // 右上角下拉导航栏
        text: "后端",
        items: [
          { text: "Linux", link: "/linux/" },
          { text: "Redis", link: "/redis/" },
          {
            // 带分割线的导航栏
            items: [
              { text: "MySql", link: "/mysql/" },
              { text: "sqlalchemy", link: "/sqlalchemy/" },
            ],
          },
          {
            items: [
              { text: "nginx", link: "/nginx/" },
              { text: "gunicorn", link: "/gunicorn/" },
            ],
          },
        ],
      },
    ], // 右上角头部导航栏
  },
};

社交链接 ​

使用 themeConfig.socialLinks 可以配置社交链接，目前支持的有

TS
type SocialLinkIcon =
  | 'discord'
  | 'facebook'
  | 'github'
  | 'instagram'
  | 'linkedin'
  | 'slack'
  | 'twitter'
  | 'youtube'
  | { svg: string }

配置如下

JS
socialLinks: [
    {icon: "github", link: "https://gitee.com/zhengxinonly"},
    // You can also add custom icons by passing SVG as string:
    {
        icon: {
            svg: '<svg t="1676025513460" class="icon" viewBox="0 0 1129 1024" version="1.1" xmlns="http://www.w3.org/2000/svg" p-id="2745" width="200" height="200"><path d="M234.909 9.656a80.468 80.468 0 0 1 68.398 0 167.374 167.374 0 0 1 41.843 30.578l160.937 140.82h115.07l160.936-140.82a168.983 168.983 0 0 1 41.843-30.578A80.468 80.468 0 0 1 930.96 76.445a80.468 80.468 0 0 1-17.703 53.914 449.818 449.818 0 0 1-35.406 32.187 232.553 232.553 0 0 1-22.531 18.508h100.585a170.593 170.593 0 0 1 118.289 53.109 171.397 171.397 0 0 1 53.914 118.288v462.693a325.897 325.897 0 0 1-4.024 70.007 178.64 178.64 0 0 1-80.468 112.656 173.007 173.007 0 0 1-92.539 25.75h-738.7a341.186 341.186 0 0 1-72.421-4.024A177.835 177.835 0 0 1 28.91 939.065a172.202 172.202 0 0 1-27.36-92.539V388.662a360.498 360.498 0 0 1 0-66.789A177.03 177.03 0 0 1 162.487 178.64h105.414c-16.899-12.07-31.383-26.555-46.672-39.43a80.468 80.468 0 0 1-25.75-65.984 80.468 80.468 0 0 1 39.43-63.57M216.4 321.873a80.468 80.468 0 0 0-63.57 57.937 108.632 108.632 0 0 0 0 30.578v380.615a80.468 80.468 0 0 0 55.523 80.469 106.218 106.218 0 0 0 34.601 5.632h654.208a80.468 80.468 0 0 0 76.444-47.476 112.656 112.656 0 0 0 8.047-53.109v-354.06a135.187 135.187 0 0 0 0-38.625 80.468 80.468 0 0 0-52.304-54.719 129.554 129.554 0 0 0-49.89-7.242H254.22a268.764 268.764 0 0 0-37.82 0z m0 0" fill="#20B0E3" p-id="2746"></path><path d="M348.369 447.404a80.468 80.468 0 0 1 55.523 18.507 80.468 80.468 0 0 1 28.164 59.547v80.468a80.468 80.468 0 0 1-16.094 51.5 80.468 80.468 0 0 1-131.968-9.656 104.609 104.609 0 0 1-10.46-54.719v-80.468a80.468 80.468 0 0 1 70.007-67.593z m416.02 0a80.468 80.468 0 0 1 86.102 75.64v80.468a94.148 94.148 0 0 1-12.07 53.11 80.468 80.468 0 0 1-132.773 0 95.757 95.757 0 0 1-12.875-57.133V519.02a80.468 80.468 0 0 1 70.007-70.812z m0 0" fill="#20B0E3" p-id="2747"></path></svg>',
        }, link: "https://space.bilibili.com/162101364",
    },] // 右上角社交链接

侧边栏 ​

侧边栏可以在 themeConfig.Sidebar 中配置，其实和 nav 配置差不多

js
sidebar: [
  {
    text: "前端",
    items: [
      {
        text: "前端基础",
        link: "/frontend/index.md",
      },
      { text: "HTML", link: "/frontend/HTML" },
      { text: "CSS", link: "/frontend/CSS" },
    ],
  },
  {
    text: "javascript",
    items: [
      { text: "js 基础", link: "/frontend/javascript" },
      { text: "js 进阶", link: "/frontend/javascript2" },
    ],
  },
]; // 侧边栏

配合导航需要新建文件，之后的目录结构如下

├─docs
│  │  getting-started.md
│  │  index.md
│  │
│  ├─.vitepress
│  │  │  config.js
│  │  │
│  ├─articles
│  │      gulp 的使用.md
│  │      pina 和 vuex.md
│  │      组件库环境搭建.md
│  │
│  ├─frontend
│  │      CSS.md
│  │      HTML.md
│  │      index.md
│  │      javascript.md
│  │      javascript2.md
│  │
│  └─python
│          index.md

不过一般不会使用这种方式配置侧边栏，因为这样每个页面都会有侧边栏。我们需要做到仅某些页面才会出现侧边栏。所以我们可以这样配置

js
sidebar: {
    "/frontend/"
:
    [
        {
            text: "前端",
            items: [
                {
                    text: "前端基础",
                    link: "/frontend/index.md",
                },
                {text: "HTML", link: "/frontend/HTML"},
                {text: "CSS", link: "/frontend/CSS"},
            ],
        },
        {
            text: "javascript",
            items: [
                {text: "js 基础", link: "/frontend/javascript",},
                {text: "js 进阶", link: "/frontend/javascript2",},
            ],
        },
    ],
}
, // 指定路径的侧边栏

可折叠侧边栏 ​

配置可折叠侧边栏只需将 collapsible 设置为 true 即可，默认初始页面是全部展开页面，如果你需要关闭状态只需要将 collapsed 设置为 true

js
sidebar: {
    "/frontend/"
:
    [
        {
            text: "javascript",
            collapsible: true,
            collapsed: true,
            items: [
                {text: "js 基础", link: "/frontend/javascript",},
                {text: "js 进阶", link: "/frontend/javascript2",},
            ],
        },
    ],
}
, // 指定路径的侧边栏

布局模式 ​

官网这章节有详细介绍 vitepress 中的三种布局模式，分别是

  • doc，文档模式
  • page，页面模式
  • home，首页模式

如果没有指定布局模式，默认使用 doc 文档模式

doc 文档模式 ​

文档模式就是，vitepress 会自动解析 md 内容，并且使用自带的样式

修改 index.md 的内容

md
---
layout: doc
---

# 标题 1

## 标题 2

### 标题 3

- 分点 1
- 分点 2
- 分点 3

1. 分点 1
2. 分点 2
3. 分点 3

然后就可以看到自带样式的 md 内容

page 页面模式 ​

页面模式就是，vitepress 会自动解析 md 内容，但不会使用自带样式

我们把 index.md 的 layout 改一下

md
---
layout: page
---

可以看到，内容已经被解析成 html 标签，但没有预设的文档样式，这个模式下可以进行自定义主题等处理

home 首页模式 ​

这是我们主要讲解模式，这个模式下会使用 vitepress 自带的组件来控制首页样式，官网这章节 也详细介绍了这模式

我们先改下 index.md 的内容，直接复制官网内容 (懒得写)

md
---
layout: home

hero:
name: VitePress
text: Vite & Vue powered static site generator.
tagline: Lorem ipsum...
image:
src: /logo.png
alt: VitePress
actions:
  - theme: brand
    text: Get Started
    link: /guide/what-is-vitepress
  - theme: alt
    text: View on GitHub
    link: https://github.com/vuejs/vitepress
---

可以看到，这时候已经是首页样式了

注意：注意缩进，不对可能导致没有内容

首页优化 ​

接下来我们开始对首页进行优化

首页图片处理 ​

我们先选择合适的图片作为图标，当然你也可以不用，把 image 属性去掉即可

在根目录下创建 public 目录，然后把选好的图片放到里面，再修改 image 属性即可

hero:
  name: VitePress
  text: Vite & Vue powered static site generator.
  tagline: Lorem ipsum...
  image:
      src: /logo.svg
      alt: VitePress

更改系统标题 ​

标题与图标 ​

这时候左上角的图标和 tab 栏的标题都还是默认的 VitePress，我们需要改成我们自己的工程名

1、在根目录下创建 .vitepress 目录，然后创建 config.ts 文件，然后输入以下内容

js
export default {
  // ...
  themeConfig: {
    // 主题配置
    siteTitle: "正心全栈编程", // 站点首页标题
    logo: "logo.svg", // 站点 logo
  },
};

2、每次改配置都需要重启工程

可以看到 tab 的标题，左上角标题都改成系统名了

修改首页展示的图片，其中 logo 的地址对应的是 public 下的图片，目录结构如下所示

.
├─ docs
│  ├─ .vitepress
│  │  └─ config.js
│  ├─ public
│  │   └─ logo.svg
│  └─ index.md
└─ package.json

这里 logo 我是用了 svg 图标，此时页面效果为

添加社交链接 ​

这里可加可不加，一般会把工程的 Github 链接带上

1、在 .vitepress/config.ts 下加上配置 socialLinks

js
import { defineConfig } from "vitepress";

export default defineConfig({
  title: "正心全栈编程",
  themeConfig: {
    logo: "logo.svg", // 站点 logo
    siteTitle: "正心全栈编程", // 站点首页标题

    socialLinks: [
      { icon: "github", link: "https://gitee.com/zhengxinonly" },
      { icon: "twitter", link: "..." },
    ], // 右上角社交链接
  },
});

可以看到右上角会出现一个 github 图标，点击就能进入预设的链接

官网介绍有以下这些模式可以使用

ts
interface SocialLink {
  icon: SocialLinkIcon;
  link: string;
}

type SocialLinkIcon =
  | "discord"
  | "facebook"
  | "github"
  | "instagram"
  | "linkedin"
  | "slack"
  | "twitter"
  | "youtube"
  | { svg: string };

添加 Features ​

官网下边可以加点 Features 来分点介绍

1、修改根目录下的 index.md ，也就是作为首页的文件

layout: home

hero:
  name: VitePress
  text: Vite & Vue powered static site generator.
  tagline: Lorem ipsum...
  image:
      src: /logo.svg
      alt: VitePress
  actions:
    - theme: brand
      text: Get Started
      link: /guide/what-is-vitepress
    - theme: alt
      text: View on GitHub
      link: https://github.com/vuejs/vitepress

features:
  - icon: ⚡️
    title: Vite, The DX that can't be beat
    details: Lorem ipsum...
  - icon: 🖖
    title: Power of Vue meets Markdown
    details: Lorem ipsum...
  - icon: 🛠️
    title: Simple and minimal, always
    details: Lorem ipsum...

这样首页就能显得没那么空，也能加上小点为系统做更详细的描述

页脚 ​

注脚功能比较好实现，vitepress 文档 也有教程，就是在 themeConfig 中添加footer属性

js
export default {
  title: "zhengxin", // 站点标题
  description: "正心的全栈编程笔记", // mate 标签 description，多用于搜索引擎抓取摘要
  themeConfig: {
    // 主题配置
    // siteTitle: "正心全栈编程", // 站点首页标题
    logo: "logo.svg", // 站点 logo
    socialLinks: [
      { icon: "github", link: "https://gitee.com/zhengxinonly" },
      { icon: "twitter", link: "..." },
    ], // 右上角社交链接
    footer: {
      message: "只教有用的",
      copyright: "2023.02.06 @zhengxinonly",
    },
  },
};