Home
avatar

YEYUbaka

vhAstro-Theme 使用手册

2932字 14.7分钟 技术分享

前言

欢迎使用 vhAstro-Theme！这是一款基于 Astro 开发的优雅博客主题，具有简洁的设计、流畅的动画和丰富的功能。本手册将详细介绍主题支持的所有 Markdown 格式和特殊组件的使用方法，帮助你快速上手并充分利用主题的各项特性。

主题特点：

  • ✅ 基于 Astro v5.13.10，性能卓越
  • ✅ 支持丰富的 Markdown 扩展语法
  • ✅ 内置多种特殊组件（音乐、视频、相册等）
  • ✅ 代码语法高亮（Shiki）
  • ✅ 数学公式支持（KaTeX）
  • ✅ 响应式设计，完美适配移动端

参考资源：

一、基础 Markdown 语法

1.1 标题

使用 # 符号创建标题，支持 H1-H6 六级标题：

# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题

1.2 文本格式

**粗体文本**
*斜体文本*
***粗斜体文本***
~~删除线文本~~
`行内代码`

效果展示：

  • 粗体文本
  • 斜体文本
  • 粗斜体文本
  • 删除线文本
  • 行内代码

1.3 列表

无序列表：

- 列表项 1
- 列表项 2
  - 嵌套列表项 2.1
  - 嵌套列表项 2.2
- 列表项 3

有序列表：

1. 第一项
2. 第二项
3. 第三项

1.4 引用块

> 这是一个引用块
> 可以包含多行内容

> 嵌套引用：
>> 这是嵌套的引用
>>> 可以多层嵌套

效果展示：

这是一个引用块 可以包含多行内容

1.5 链接和图片

[链接文字](https://example.com)
![图片描述](/blog/images/example.jpg)

注意： 所有图片路径必须包含 /blog/ 前缀！

1.6 分隔线

---
或
***

1.7 表格

| 列1 | 列2 | 列3 |
|-----|-----|-----|
| 内容1 | 内容2 | 内容3 |
| 内容4 | 内容5 | 内容6 |

| 左对齐 | 居中对齐 | 右对齐 |
|:-------|:--------:|-------:|
| 左 | 中 | 右 |

效果展示：

功能支持说明
Markdown✅完整支持
代码高亮✅Shiki 引擎
数学公式✅KaTeX 渲染

二、特殊提示框组件

vhAstro-Theme 支持多种类型的提示框，用于突出显示重要信息。

2.1 默认提示框

:::note
这是一个默认提示框
:::

这是一个默认提示框，用于一般性提示信息。

2.2 信息提示框（蓝色）

:::note{type="info"}
这是一个信息提示框
:::

这是一个信息提示框，用于提供额外的信息说明。

2.3 成功提示框（绿色）

:::note{type="success"}
这是一个成功提示框
:::

这是一个成功提示框，用于显示操作成功或正面信息。

2.4 警告提示框（黄色）

:::note{type="warning"}
这是一个警告提示框
:::

这是一个警告提示框，用于提醒用户注意潜在问题。

2.5 错误提示框（红色）

:::note{type="error"}
这是一个错误提示框
:::

这是一个错误提示框，用于显示错误信息或严重警告。

2.6 重要提示框（紫色）

:::note{type="import"}
这是一个重要提示框
:::

这是一个重要提示框，用于强调关键信息或重要说明。

三、代码块和语法高亮

3.1 行内代码

使用单个反引号包裹代码：`code`

示例：这是一个 console.log() 函数调用。

3.2 代码块

使用三个反引号包裹代码块，并指定语言以启用语法高亮：

JavaScript 示例：

// JavaScript 代码示例
function greet(name) {
  console.log(`Hello, ${name}!`);
}

greet("vhAstro-Theme");

TypeScript 示例：

// TypeScript 代码示例
interface User {
  name: string;
  age: number;
}

const user: User = {
  name: "YEYUbaka",
  age: 25
};

Python 示例：

# Python 代码示例
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

print(fibonacci(10))

Bash 示例：

# Bash 脚本示例
#!/bin/bash
echo "Hello, World!"
npm run bui deploy

HTML 示例：

<!-- HTML 代码示例 -->
<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>vhAstro-Theme</title>
</head>
<body>
  <h1>欢迎使用 vhAstro-Theme</h1>
</body>
</html>

CSS 示例：

/* CSS 样式示例 */
.container {
  max-width: 1200px;
  margin: 0 auto;
  padding: 20px;
}

.title {
  font-size: 2rem;
  color: #333;
  font-weight: bold;
}

JSON 示例：

{
  "name": "vhAstro-Theme",
  "version": "1.0.0",
  "description": "优雅的 Astro 博客主题",
  "author": "韩小韩",
  "license": "MIT"
}

3.3 支持的语言

主题使用 Shiki 语有主流编程语言：

  • JavaScript / TypeScript
  • Python / Java / C++ / C# / Go / Rust
  • HTML / CSS / SCSS / Less
  • Markdown / JSON / YAML / TOML
  • Bash / PowerShell / Shell
  • SQL / GraphQL
  • 以及更多…

3.4 代码块特性

  • ✅ 自动复制按钮：每个代码块都会自动添加复制按钮
  • ✅ 语法高亮：使用 github-light 主题
  • ✅ 行号显示：自动显示行号（可配置）

四、媒体组件

4.1 音乐播放器组件

vhAstro-Theme 支持嵌入网易云音乐播放器。

单曲播放：

::vhMusic{id="3346844433"}

歌单播放：

::vhMusic{id="3187536304" type="playlist"}

参数说明：

  • id：网易云音乐的歌曲或歌单 ID
  • type：播放类型，song（单曲，默认）或 playlist（歌单）

如何获取音乐 ID：

  1. 打开网易云音乐网页版
  2. 找到想要分享的歌曲或歌单
  3. 从 URL 中获取 ID，例如：
    • 歌曲：https://music.163.com/#/song?id=3346844433 → ID 是 3346844433
    • 歌单：https://music.163.com/#/playlist?id=3187536304 → ID 是 3187536304

效果展示：

单曲播放

歌单播放

4.2 视频播放器组件

支持嵌入视频播放器，可播放 MP4、M3U8 等格式。

语法格式：

::vhVideo{url="https://example.com/video.mp4"}

参数说明：

  • url：视频文件的 URL 地址

注意事项：

  • 视频 URL 必须是可访问的公网地址
  • 支持 MP4、WebM、M3U8 等格式
  • 播放器会自动适配移动端

4.3 实况照片组件

实况照片（Live Photo）是一种结合静态图片和短视频的媒体形式。

竖向实况照片：

::vhLivePhoto{photo="/blog/images/photo.jpg" video="/blog/images/video.mp4" type="y"}

横向实况照片：

::vhLivePhoto{photo="/blog/images/photo.jpg" video="/blog/images/video.mp4" type="x"}

参数说明：

  • photo：静态图片的路径
  • video：视频文件的路径
  • type：方向类型，x（横向）或 y（竖向）

4.4 图片相册组件

创建图片相册，支持多图展示和点击放大。

语法格式：

:::picture
![图片1](/blog/images/pic1.jpg)
![图片2](/blog/images/pic2.jpg)
![图片3](/blog/images/pic3.jpg)
:::

特性：

  • ✅ 自动网格布局

  • ✅ 响应式设计

  • ✅ 点击放大查看

  • ✅ 懒加载优化

图片1

五、按钮组件

创建美观的按钮链接。

语法格式：

::btn[按钮文字]{link="https://example.com"}

效果展示：

访问 GitHub 返回首页

特性：

  • ✅ 自动添加 target="_blank" 属性
  • ✅ 美观的悬停效果
  • ✅ 响应式设计

六、数学公式

vhAstro-Theme 支持 LaTeX 数学公式，使用 KaTeX 渲染。

6.1 行内公式

使用单个 $ 包裹公式：

这是一个行内公式：$E=mc^2$

效果展示：

这是一个行内公式：E=mc2E=mc^2

6.2 块级公式

使用双 $$ 包裹公式：

$$
\int_{a}^{b} f(x) dx = F(b) - F(a)
$$

效果展示：

∫abf(x)dx=F(b)−F(a)\int_{a}^{b} f(x) dx = F(b) - F(a)

6.3 更多公式示例

二次方程求根公式：

x=−b±b2−4ac2ax = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}

矩阵表示：

[abcd]\begin{bmatrix} a & b \\ c & d \end{bmatrix}

求和公式：

∑i=1ni=n(n+1)2\sum_{i=1}^{n} i = \frac{n(n+1)}{2}

极限表示：

lim⁡x→∞1x=0\lim_{x \to \infty} \frac{1}{x} = 0

七、高级技巧

7.1 图片懒加载

主题自动为所有图片启用懒加载，优化页面加载速度。

工作原理：

  • 图片初始显示占位图
  • 滚动到可视区域时加载真实图片
  • 自动添加 loading="lazy" 属性

7.2 外链自动处理

所有外部链接自动添加以下属性：

  • target="_blank"：在新标签页打开
  • rel="noopener nofollow"：安全和 SEO 优化

7.3 代码块复制功能

每个代码块自动添加复制按钮：

  • 点击按钮一键复制代码
  • 复制成功后显示提示
  • 支持所有代码语言

7.4 图片点击放大

片支持点击放大查看：

  • 点击图片进入全屏模式
  • 支持缩放和拖拽
  • ESC 键退出全屏

7.5 文章字数和阅读时间

主题自动计算文章字数和预估阅读时间：

  • 基于文章内容自动统计
  • 显示在文章头部
  • 帮助读者评估阅读时长

八、Front Matter 配置说明

每篇文章的头部需要配置 Front Matter，用于设置文章的元信息。

8.1 完整配置示例

---
title: "文章标题"
date: 2026-02-09T00:00:00+08:00
categories: "技术分享"
id: "20260209"
cover: /blog/images/posts/cover.jpg
tags:
  - 标签1
  - 标签2
  - 标签3
recommend: true
top: true
hide: false
author: "作者名称"
description: "文章描述，用于 SEO 和摘要显示"
showToc: true
---

8.2 配置项说明

配置项类型必填说明
titleString✅文章标题
dateDateTime✅发布日期（ISO 8601 格式）
categoriesString✅文章分类
idString✅文章唯一 ID（格式：YYYYMMDD）
coverString❌封面图片路径（必须包含 /blog/ 前缀）
tagsArray❌标签数组
recommendBoolean❌是否推荐（默认 false）
topBoolean❌是否置顶（默认 false）
hideBoolean❌是否隐藏（默认 false）
authorString❌作者名称
descriptionString❌文章描述
showTocBoolean❌是否显示目录（默认 true）

8.3 日期格式说明

日期必须使用 ISO 8601 格式：

date: 2026-02-09T00:00:00+08:00

26-02-09`：年-月-日

  • T：日期和时间的分隔符
  • 00:00:00：时:分
  • +08:00：时区（东八区）

8.4 文章 ID 规范

文章 ID 使用日期格式（YYYYMMDD）：

id: "20260209"

注意事项：

  • 必须是 8 位数字
  • 格式：年（4位）+ 月（2位）+ 日（2位）
  • 确保唯一性，不与现有文章冲突

九、写作最佳实践

9.1 文章结构建议

一篇优秀的博客文章应包含：

  1. 前言：简要介绍文章主题和背景
  2. 目录：使用 showToc: true 自动生成
  3. 正文：分段清晰，使用标题组织内容
  4. 代码示例：提供完整可运行的代码
  5. 效果展示：使用截图或实际效果
  6. 总结：概括要点和心得体会
  7. 参考资源：列出相关链接和资料

9.2 图片使用建议

  • ✅ 使用 WebP 格式以优化加载速度
  • ✅ 图片宽度建议 1200px 以内
  • ✅ 封面图片建议尺寸：1200x630px
  • ✅ 所有图片路径必须包含 /blog/ 前缀
  • ✅ 为图片添加有意义的 alt 文本

9.3 代码示例建议

-启用语法高亮

  • ✅ 添加注释说明关键代码
  • ✅ 提供完整可运行的示例
  • ✅ 避免过长的代码块（超过 50 行考虑分段）

9.4 SEO 优化建议

  • ✅ 填写准确的 description
  • ✅ 使用相关的 tags
  • ✅ 标题简洁明了（50 字以内）
  • ✅ 使用合适的标题层级（H1-H6）
  • ✅ 添加内部链接和外部参考

十、常见问题

10.1 图片不显示？

可能原因：

  1. 图片路径缺少 /blog/ 前缀
  2. 图片文件不存在
  3. 图片路径大小写错误

解决方案：

<!-- ❌ 错误 -->
![图片](/images/example.jpg)

<!-- ✅ 正确 -->
![图片](/blog/images/example.jpg)

10.2 代码块没有语法高亮？

可能原因：

  • 没有指定代码语言

解决方案：

<!-- ❌ 错误 -->
```
console.log("Hello");
```

<!-- ✅ 正确 -->
```javascript
console.log("Hello");
```

10.3 数学公式不显示？

可能原因：

  • 使用了错误的分隔符
  • LaTeX 语法错误

解决方案：

<!-- ❌ 错误 -->
\(E=mc^2\)

<!-- ✅ 正确 -->
$E=mc^2$

10.4 音乐播放器不工作？

可能原因：

  1. 音乐 ID 错误
  2. 网易云音乐 API 配置问题
  3. 网络连接问题

解决方案：

  • 检查音乐 ID 是否正确
  • 确认 config.ts 中配置了 vhMusicApi
  • 尝试使用其他歌曲 ID

十一、参考资源

11.1 官方资源

11.2 Markdown 资源

11.3 数学公式资源

11.4 其他资源

结语

恭喜你！现在你已经掌握了 vhAstro-Theme 的所有使用方法。这份手册涵盖了从基础 Markdown 语法到高级组件的完整内容，希望能帮助你创作出优秀的博客文章。

写作建议：

  • 📝 保持文章结构清晰，使用标题组织内容
  • 🎨 合理使用提示框和组件，增强文章可读性
  • 💻 提供完整的代码示例，方便读者学习
  • 🖼️ 使用图片和媒体丰富文章内容
  • 🔍 注意 SEO 优化，提高文章曝光度

如果在使用过程中遇到问题，欢迎通过以下方式联系：

  • 📧 邮件：[你的邮箱]
  • 🐙 GitHub：[你的 GitHub]
  • 💬 留言：在本文下方评论区留言

祝你写作愉快！✨

相关链接：

Astro 博客 主题 教程 Markdown