Yukina 博客完整使用指南

欢迎使用 Yukina 博客系统！这是一个基于 Astro 的现代化博客主题，本指南将带你从零开始掌握博客的使用、Markdown 语法和各种高级功能。

🚀 快速开始

环境准备

# 安装依赖
npm install

# 开发模式
npm run dev

# 构建生产版本
npm run build

# 预览构建结果
npm run preview

基本配置

编辑 yukina.config.ts 文件进行个性化设置：

const YukinaConfig: Configuration = {
  title: "我的博客",
  subTitle: "记录技术与生活",
  description: "一个专注于技术分享的个人博客",
  site: "https://yourdomain.com",
  
  username: "你的昵称",
  sign: "你的个性签名",
  avatarUrl: "你的头像URL",
  
  socialLinks: [
    {
      icon: "line-md:github-loop",
      link: "https://github.com/yourusername",
    },
    // 更多社交链接...
  ],
};

📝 Markdown 写作指南

创建新文章

在 src/contents/posts/ 目录下创建 .md 文件：

---
title: 文章标题
published: 2025-01-31
description: 文章描述
tags: [技术, 教程]
category: 技术
draft: false
cover: "封面图片URL（可选）"
---

# 文章内容

这里开始写你的文章...

前置元数据说明

• title: 文章标题（必需）
• published: 发布日期（必需）
• description: 文章描述，显示在卡片和SEO中
• tags: 标签数组，用于分类和检索
• category: 文章分类
• draft: 草稿状态，true 时不会发布
• cover: 封面图片 URL

基础 Markdown 语法

标题层级

# 一级标题
## 二级标题  
### 三级标题

文本格式化

• 斜体文本 或 斜体文本
• 粗体文本 或 粗体文本
• 粗斜体文本
• 删除线文本

列表

无序列表：

• 第一项
• 第二项
  • 嵌套项目
  • 另一个嵌套项目

有序列表：

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

任务列表：

• 已完成的任务
• 待完成的任务

链接和图片

[链接文本](https://example.com "可选标题")
![图片描述](图片URL "可选标题")

高级语法功能

表格

功能	支持情况	说明
基础语法	✅	完全支持
扩展语法	✅	GitHub风格
数学公式	✅	KaTeX渲染

代码展示

行内代码：const greeting = "Hello World"

代码块：

function createBlog(title) {
    return {
        title: title,
        published: new Date(),
        content: "开始写作吧！"
    };
}

const myBlog = createBlog("我的第一篇文章");
console.log(myBlog);

引用块

这是一个引用块。

引用可以跨越多个段落。

这是嵌套引用。

数学公式

支持 KaTeX 数学公式渲染：

内联公式：质能方程 $E = mc^2$

块级公式：

$$\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}$$

二次方程求根公式：

$$x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$$

多媒体内容

嵌入视频

YouTube 视频：

<iframe width="100%" height="400" 
src="https://www.youtube.com/embed/VIDEO_ID" 
title="视频标题" frameborder="0" allowfullscreen>
</iframe>

哔哩哔哩视频：

<iframe width="100%" height="400" 
src="//player.bilibili.com/player.html?bvid=BV_ID&p=1" 
scrolling="no" border="0" frameborder="no" allowfullscreen>
</iframe>

HTML 内联

Markdown 支持内联 HTML，实现更丰富的效果：

点击展开更多信息

这里是折叠的内容，点击上方可以展开或收起。

• 列表项目一
• 列表项目二
• 列表项目三

🎨 主题自定义

颜色主题

在 src/components/GlobalStyles.astro 中修改颜色变量：

:root {
  --hue: 300; /* 主色调：0-360 */
  --primary-color: oklch(70% 0.15 var(--hue));
  --background-color: oklch(97% 0.01 var(--hue));
}

.dark {
  --primary-color: oklch(70% 0.125 var(--hue));
  --background-color: oklch(17.5% 0.015 var(--hue));
}

添加自定义页面

1. 在 src/pages/ 创建 .astro 文件
2. 在 yukina.config.ts 的 navigators 中添加导航链接：

navigators: [
  { nameKey: "page.home", href: "/" },
  { nameKey: "page.archive", href: "/archive" },
  { nameKey: "page.about", href: "/about" },
  { nameKey: "page.custom", href: "/custom" }, // 新页面
],

🔍 搜索与导航

搜索功能

• 基于 Pagefind 的全文搜索
• 自动索引所有页面内容
• 支持中文分词
• 实时搜索建议
• 移动端优化界面

标签和分类

使用标签和分类来组织文章：

tags: [前端, React, TypeScript]
category: 技术分享

访问路径：

• 标签页面：/tags/react
• 分类页面：/categories/技术分享
• 归档页面：/archive

📱 响应式特性

博客在不同设备上的表现：

• 桌面端：完整侧边栏 + 主内容区
• 平板端：自适应布局调整
• 移动端：折叠导航 + 底部菜单

🚀 部署指南

Vercel 部署（推荐）

1. 将代码推送到 GitHub/GitLab
2. 在 Vercel 导入项目
3. 构建设置：
   • 构建命令：npm run build
   • 输出目录：dist
   • Node.js 版本：18.x

其他静态托管平台

• Netlify：拖拽 dist 文件夹
• GitHub Pages：使用 GitHub Actions
• Cloudflare Pages：连接仓库自动部署

💡 写作最佳实践

内容组织

1. 结构清晰：使用合理的标题层级
2. 标签规范：保持标签的一致性和简洁性
3. 描述完整：为每篇文章添加描述和封面
4. 定期维护：及时更新过时内容

性能优化

1. 图片优化：使用 WebP 格式，控制文件大小
2. 代码简洁：避免过长的代码块
3. 链接检查：定期检查外链的有效性

SEO 优化

1. 元数据完整：填写 title、description、tags
2. 标题语义化：使用有意义的标题
3. 内容质量：原创、有价值的内容
4. 内链建设：文章间相互引用

🔧 高级功能

脚注支持

这里有一个脚注引用¹，还有另一个²。

键盘快捷键

使用键盘快捷键：Ctrl + C 复制

特殊标记

• 上标：H₂O
• 下标：E = mc²
• 高亮：==重要内容==

📚 实用示例

API 文档示例

## 用户 API

### GET /api/users

获取用户列表

**参数：**
- `page`: 页码（可选，默认1）
- `limit`: 每页数量（可选，默认10）

**响应：**
```json
{
  "data": [
    {
      "id": 1,
      "name": "张三",
      "email": "zhangsan@example.com"
    }
  ],
  "meta": {
    "total": 100,
    "page": 1
  }
}

项目 README 模板

# 项目名称

项目的简短描述

## 功能特性

- ✅ 特性一
- ✅ 特性二  
- 🚧 开发中的特性

## 安装使用

```bash
npm install project-name

贡献指南

欢迎提交 Issue 和 Pull Request！

## 🎯 总结

通过本指南，你已经掌握了：

1. **基础配置**：环境搭建和基本设置
2. **Markdown 语法**：从基础到高级的完整语法
3. **内容创作**：文章写作和多媒体嵌入
4. **主题自定义**：颜色和布局调整
5. **部署发布**：多平台部署方案

### 下一步建议

- 开始写你的第一篇文章
- 根据需求自定义主题颜色
- 设置好搜索引擎优化
- 定期备份和更新内容

记住：**优秀的博客需要持续的内容输出和不断的优化改进**。

---

*希望这个完整指南能帮助你快速上手 Yukina 博客系统！如有疑问，欢迎查看项目文档或提交 Issue。*

**最后更新时间**：2025年1月31日

Footnotes

1. 这是第一个脚注的内容。 ↩

2. 这是一个带名称的脚注。 ↩