VitePress基础框架

主题

首页配置 ​

配置图 ​

首页配置图片

网站图标和标题 ​

config.mts
ts
export default defineConfig({
	title: 'VitePress基础框架', // 标题
	// Head配置
	head: [
		['link', { rel: 'icon', type: 'image/svg+xml', href: '/vitepress-template/logo/vitepress-logo-mini.svg' }], // 网站图标
		['link', { rel: 'icon', type: 'image/png', href: '/vitepress-template/logo/vitepress-logo-mini.png' }], // 网站图标
	],
});

导航 LOGO 和标题 ​

config.mts
ts
export default defineConfig({
	// 主题配置
	themeConfig: {
		// 左侧导航栏图标也可直接'/logo/vitepress-logo-mini.svg'
		logo: { src: '/logo/vitepress-logo-mini.svg', width: 24, height: 24 },
		siteTitle: 'VitePress基础框架', // 左侧导航栏标题
	},
});

导航栏 ​

config.mts
ts
export default defineConfig({
	// 主题配置
	themeConfig: {
		// 导航菜单
		nav: nav(),
	},
});
// 导航菜单
function nav(): DefaultTheme.NavItem[] {
	return [
		{
			text: '教程', // 导航栏标题
			link: '/guide/install', // 导航栏路径
			activeMatch: '/guide', // 动态匹配路径，高亮显示
		},
		{
			text: '示例',
			link: '/examples/markdown',
			activeMatch: '/examples',
		},
		{
			text: '下拉导航',
			items: [
				{
					text: '下拉导航标题', // 该部分的标题，也可以省略标题
					items: [
						{
							text: '子项A',
							link: 'https://github.com/dcdy/vitepress-template/edit/main/docs/.vitepress/config.mts',
						},
						{
							text: '子项B',
							link: 'https://gitee.com/xia_mei_ting/vitepress-template/blob/main/docs/.vitepress/config.mts',
						},
					],
				},
			],
		},
	];
}

深浅主题切换 ​

config.mts
ts
export default defineConfig({
	// 主题配置
	themeConfig: {
		appearance: true, // 外观切换 - 深色浅色
		darkModeSwitchLabel: '主题', // 用于自定义悬停时显示的深色模式开关标题。
		lightModeSwitchTitle: '切换到浅色模式', // 用于自定义悬停时显示的浅色模式开关标题。
		darkModeSwitchTitle: '切换到深色模式', // 用于自定义深色模式开关标签，该标签仅在移动端视图中显示。
	},
});

友情连接 ​

config.mts
ts
export default defineConfig({
	// 主题配置
	themeConfig: {
		socialLinks: [
			// github友情连接
			{ icon: 'github', link: 'https://github.com/dcdy/vitepress-template' },
			// gitee友情连接(自定义图标)
			{
				icon: {
					svg: '<svg t="1727428813465" class="icon" viewBox="0 0 1024 1024" version="1.1" xmlns="http://www.w3.org/2000/svg" p-id="2268" width="200" height="200"><path d="M512 1024C229.222 1024 0 794.778 0 512S229.222 0 512 0s512 229.222 512 512-229.222 512-512 512z m259.149-568.883h-290.74a25.293 25.293 0 0 0-25.292 25.293l-0.026 63.206c0 13.952 11.315 25.293 25.267 25.293h177.024c13.978 0 25.293 11.315 25.293 25.267v12.646a75.853 75.853 0 0 1-75.853 75.853h-240.23a25.293 25.293 0 0 1-25.267-25.293V417.203a75.853 75.853 0 0 1 75.827-75.853h353.946a25.293 25.293 0 0 0 25.267-25.292l0.077-63.207a25.293 25.293 0 0 0-25.268-25.293H417.152a189.62 189.62 0 0 0-189.62 189.645V771.15c0 13.977 11.316 25.293 25.294 25.293h372.94a170.65 170.65 0 0 0 170.65-170.65V480.384a25.293 25.293 0 0 0-25.293-25.267z" fill="#C71D23" p-id="2269"></path></svg>',
				},
				link: 'https://gitee.com/xia_mei_ting/vitepress-template',
			},
		],
	},
});

主题美化 ​

主题内容 ​

注意

LOGO 文件放在docs/public/logo下，也可以直接放在 public 文件夹下，src 路径需改为/vitepress-logo-large.webp，其他图片文件同理

index.md
markdown
---
hero:
    name: VitePress 基础框架 # 标题
    text: VitePress 基础框架的站点描述 # 站点描述副标题
    tagline: VitePress 基础框架的宣传词 # 宣传词
    image: # LOGO
        src: /logo/vitepress-logo-large.webp
        alt: VitePress 基础框架 LOGO
---

美化文字和 LOGO 背景 ​

新建文件docs/.vitepress/theme/index.ts和docs/.vitepress/theme/custom.css

index.ts
ts
import DefaultTheme from 'vitepress/theme';
import './custom.css';

export default DefaultTheme;
custom.css
css
/**
-   Component: Home 首页
-   -------------------------------------------------------------------------- */
:root {
	/* 首页文字（VitePress基础框架）颜色 */
	--vp-home-hero-name-color: transparent;
	--vp-home-hero-name-background: -webkit-linear-gradient(120deg, #bd34fe 30%, #41d1ff);
	/* 首页大logo的背景色 */
	--vp-home-hero-image-background-image: linear-gradient(-45deg, #bd34fe 50%, #47caff 50%);
	--vp-home-hero-image-filter: blur(44px);
}
@media (min-width: 640px) {
	:root {
		--vp-home-hero-image-filter: blur(56px);
	}
}

@media (min-width: 960px) {
	:root {
		--vp-home-hero-image-filter: blur(68px);
	}
}

提醒

下面代码示例为：改变整体主题颜色为#a05aff 紫色

custom.css
css
:root {
	/* 主题色 */
	--vp-c-indigo-1: #a05aff; /~ 主题色 ~/
	--vp-c-indigo-2: #bd34fe; /~ 主题色-hover ~/
	--vp-c-indigo-3: #a05aff; /~ 实底色的颜色，例如按钮的 bg 颜色 ~/
}

actions 按钮 ​

普通 action ​

index.md
markdown
---
hero:
    actions: # 按钮
        - theme: brand # 选中状态
          text: 快速开始
          link: /guide/install
        - theme: alt # 未选中状态
          text: 示例
          link: /examples/markdown
---

自定义 action ​

提醒

自定义 action 中 theme 的值会是该 action 的 class 值，所以可以直接在 custom.css 中修改该 action 的样式

index.md
markdown
---
hero:
    actions: # 按钮
        - theme: custom-action
          text: 自定义 action
          link: /guide/config-home#自定义-action
---
custom.css
css
/**
   * Component: 自定义actions按钮
   * -------------------------------------------------------------------------- */
.action .VPButton.custom-action {
	position: relative;
	background-color: #ffd859;
	padding-left: 45px;
	color: #000;
}
.action .VPButton.custom-action::before {
	content: '';
	position: absolute;
	left: 20px;
	top: 50%;
	transform: translateY(-50%);
	width: 20px;
	height: 20px;
	background-image: url('/logo/vitepress-logo-mini.png');
	background-size: 20px 20px;
	background-repeat: no-repeat;
	background-position: center;
}

.VPFeature img {
	width: 30px;
	height: 30px;
	padding: 9px;
	border-radius: 6px;
	box-sizing: content-box;
	background-color: var(--vp-c-default-soft);
}

自定义插槽 action ​

  1. 新建文件docs/.vitepress/theme/components/CustomLayoutSlot.vue文件
点击查看 CustomLayoutSlot.vue 文件的代码
CustomLayoutSlot.vue
vue
<!-- 自定义布局插槽 -->
<template>
	<Layout>
		<template #home-hero-actions-after>
			<div class="custom-action-plain">
				<img src="/logo/vitepress-logo-mini.png" alt="action-logo" />
				<a href="./guide/config-home#自定义插槽-action">自定义插槽action</a>
			</div>
		</template>
	</Layout>
</template>
<script setup>
// 导入主题布局组件
import DefaultTheme from 'vitepress/theme';
const { Layout } = DefaultTheme;
</script>
<style lang="scss">
// 设置自定义插槽action样式
.custom-action-plain {
	position: relative;
	display: inline-flex;
	justify-content: center;
	align-items: center;
	height: 40px;
	margin-top: 20px;
	padding: 4px 24px;
	border-radius: 100px;
	font-size: 14px;
	font-weight: 600;
	white-space: nowrap;
	background-color: var(--vp-c-bg-elv);
	cursor: pointer;
	img {
		width: 20px;
		height: 20px;
		margin-right: 6px;
	}
}
.custom-action-plain:hover::before {
	background-image: linear-gradient(var(--rotate), #ffd859, #ff5555 43%, #a805be);
}
.custom-action-plain::before {
	content: '';
	position: absolute;
	top: -3px;
	left: -3px;
	z-index: -1;
	width: calc(100% + 6px);
	height: calc(100% + 6px);
	border-radius: 100px;
	animation: spin 3s linear infinite;
	background-image: linear-gradient(var(--rotate), #a805be, #3c67e3 43%, #4e00c2);
}

@keyframes spin {
	0% {
		--rotate: 0deg;
	}
	100% {
		--rotate: 360deg;
	}
}
@property --rotate {
	syntax: '<angle>';
	initial-value: 132deg;
	inherits: false;
}
</style>
  1. theme 文件夹下的 index.ts 中引入CustomLayoutSlot.vue文件
index.ts
ts
import DefaultTheme from 'vitepress/theme';
import './custom.css';
import MyLayout from './components/CustomLayoutSlot.vue';

export default {
	extends: DefaultTheme,
	// 使用注入插槽的包装组件覆盖 Layout
	Layout: MyLayout,
};

Features 部分 ​

提醒

普通 feature 部分使用title 作为标题， icon 作为图标，details 作为描述； icon 有三种写法

  1. 直接放一个 emoji 图标或 svg 代码。例：下面标题为“内容丰富”的 icon 代码
  2. 直接放一个 svg 图标（width 和 height 可以不加）。例：下面标题为“注释详尽”的 icon 代码
  3. 区分 dark 和 light 两种图标（width 和 height 可以不加）。例：下面标题为“高效构建”的 icon 代码
index.md
markdown
---
hero:
    features: # 特性
        - title: 内容丰富
          icon: 📚
          details: 模板精心设计了内容结构，支持从小型项目到大型文档的全面组织，确保每个细节都能够清晰呈现，帮助用户快速查找所需信息。
        - title: 注释详尽
          icon:
              src: /features_icon/features-icon-1.svg
              width: 30px
              height: 30px
          details: 每一处配置、每一个功能都有详细的注释说明，确保即使是新手也能轻松理解和使用，让文档维护和二次开发变得更加简单。
        - title: 高效构建
          icon:
              dark: /features_icon/features-icon-2.svg
              light: /features_icon/features-icon-3.svg
              width: 30px
              height: 30px
          details: 基于 Vite 的超快构建和热更新特性，让文档编写和预览流畅无阻。无论文档规模多大，都能保持快速响应和高效加载。
---

底部版权信息 ​

config.mts
js
export default defineConfig({
    // 主题配置
	themeConfig: {
        footer: {
			// 有 sidebar 时不显示
			message: '基于MIT许可发布',
			copyright: `版权所有 © ${
				new Date().getFullYear() == 2024 ? 2024 : 2024 + '-' + new Date().getFullYear()
			} dcdyxmt@163.com`,
		}
    }
}）

基于MIT许可发布

版权所有 © 2024 dcdyxmt@163.com