Yukina 博客系统使用指南

Yukina 是一个基于 Astro 的现代博客主题，具有简洁美观的设计和丰富的功能。本文将详细介绍如何使用和自定义这个博客系统。

🚀 快速开始

安装依赖

npm install

开发模式

npm run dev

构建生产版本

npm run build

预览构建结果

npm run preview

📝 写作指南

创建新文章

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

---
title: 文章标题
published: 2025-01-24
description: 文章描述
tags: [标签1, 标签2]
category: 分类
draft: false
---

# 文章内容

这里是文章的正文内容...

前置元数据说明

• title: 文章标题（必需）
• published: 发布日期（必需）
• description: 文章描述（可选）
• tags: 标签数组（可选）
• category: 分类（可选）
• draft: 是否为草稿（可选，默认 false）
• cover: 封面图片 URL（可选）
• author: 作者（可选）
• licenseName: 自定义许可证名称（可选）
• licenseUrl: 自定义许可证链接（可选）

Markdown 语法支持

Yukina 支持完整的 Markdown 语法，包括：

• 基础语法: 标题、段落、列表、链接、图片等
• 扩展语法: 表格、代码块、删除线等
• 数学公式: 支持 KaTeX 渲染
• 代码高亮: 支持多种编程语言

数学公式示例

内联公式：$E = mc^2$

块级公式：

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

代码块示例

function greet(name) {
    console.log(`你好，${name}！`);
}

greet("世界");

🎨 自定义配置

基本配置

编辑 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",
    },
    // 添加更多社交链接...
  ],
  
  banners: [
    "横幅图片URL1",
    "横幅图片URL2",
    // 添加更多图片...
  ],
};

主题自定义

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

:root {
  --hue: 300; /* 主色调 */
  --primary-color: oklch(70% 0.15 var(--hue));
  /* 其他颜色变量... */
}

添加自定义页面

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

🔍 搜索功能

Yukina 集成了 Pagefind 搜索功能：

• 自动索引所有页面内容
• 支持中文搜索
• 实时搜索结果
• 移动端友好的搜索界面

📱 响应式设计

博客在各种设备上都有良好的显示效果：

• 桌面端: 完整的侧边栏和导航
• 平板端: 自适应布局
• 移动端: 折叠式导航和搜索

🌍 国际化

支持中文和英文界面：

• 在 yukina.config.ts 中设置 locale
• 在 src/locales/languages/ 中添加翻译
• 自动根据语言设置显示对应文本

🚀 部署

Vercel 部署

1. 将代码推送到 GitHub
2. 在 Vercel 中导入项目
3. 设置构建命令为 npm run build
4. 设置输出目录为 dist

其他平台

由于 Yukina 生成静态文件，可以部署到任何静态托管平台：

• Netlify
• GitHub Pages
• Cloudflare Pages
• 等等

💡 最佳实践

文章组织

• 使用有意义的文件名
• 合理使用标签和分类
• 添加适当的描述
• 定期整理和更新内容

性能优化

• 优化图片大小和格式
• 使用 WebP 格式图片
• 合理使用封面图片
• 定期清理无用文件

SEO 优化

• 填写完整的元数据
• 使用描述性的标题
• 添加适当的标签
• 保持内容质量

🔧 故障排除

常见问题

1. 构建失败: 检查 Markdown 语法和前置元数据
2. 搜索不工作: 确保已正确构建并部署
3. 样式问题: 检查 Tailwind CSS 配置
4. 图片不显示: 检查图片 URL 和路径

获取帮助

• 查看 GitHub Issues
• 阅读 Astro 文档
• 参考本博客的其他教程文章

结语

Yukina 是一个功能丰富且易于自定义的博客系统。通过本指南，你应该能够快速上手并创建属于自己的博客。

如果你有任何问题或建议，欢迎在 GitHub 上提出 Issue 或 Pull Request！

---

希望这个指南对你有帮助！