Jiao77/NovaBlog
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4ba51e17552f8cc2b8720a817a24f288b90d5068
NovaBlog/docs/user-guide.md
Jiao77 4ba51e1755 update docs
2026-03-01 13:04:52 +08:00

11 KiB
Raw Blame History

NovaBlog 使用指南

欢迎使用 NovaBlog！这是一款面向程序员和极客的轻量级混合架构博客系统。本指南将帮助您快速上手使用 NovaBlog 的各项功能。

目录

  1. 快速开始
  2. 文章管理
  3. MDX 组件使用
  4. Typst 学术排版
  5. 动效 HTML 块
  6. 评论系统
  7. 用户注册与登录
  8. 主题定制
  9. 附件管理
  10. 常见问题

快速开始

环境要求

  • Node.js 18+
  • Go 1.21+ (仅后端开发需要)
  • Typst 0.11+ (可选，用于数学公式渲染)

启动开发服务器

# 启动前端开发服务器
npm run dev

# 启动后端 API 服务器
cd server && go run cmd/server/main.go

访问 http://localhost:4321 即可预览博客。

文章管理

创建新文章

所有文章存放在 src/content/blog/ 目录下，支持 .md 和 .mdx 格式。

文章命名规范

推荐使用以下命名格式：

  • my-first-post.md - 英文，小写，连字符分隔
  • 使用指南.md - 中文也可以，但 URL 会进行编码

Frontmatter 字段说明

每篇文章需要在开头添加 Frontmatter 元数据：

---
title: 文章标题
description: 文章描述，用于 SEO 和社交分享
pubDate: 2024-01-15
updatedDate: 2024-01-20  # 可选，更新日期
heroImage: /images/cover.jpg  # 可选，封面图
heroAlt: 封面图描述  # 可选
author: 作者名  # 可选，默认为站点名称
tags:  # 可选，标签列表
  - JavaScript
  - 教程
category: 技术  # 可选，分类
---

文章内容从这里开始...

示例文章

---
title: 我的第一篇博客
description: 这是我使用 NovaBlog 发布的第一篇文章
pubDate: 2024-01-15
heroImage: /images/hello-world.jpg
tags:
  - 随笔
  - 博客
category: 生活
---

## 欢迎来到我的博客

这是正文内容。支持标准 Markdown 语法。

### 列表

- 项目 1
- 项目 2
- 项目 3

### 代码块

```javascript
console.log('Hello, NovaBlog!');

引用

这是一段引用文字。


### 文章状态

目前文章发布即公开，后续版本将支持：
- `draft: true` - 草稿状态
- `published: false` - 隐藏文章

### 删除文章

直接删除 `src/content/blog/` 目录下的对应文件即可。

---

## MDX 组件使用

NovaBlog 原生支持 MDX，允许在 Markdown 中嵌入交互式组件。

### 什么是 MDX？

MDX = Markdown + JSX。它让您可以在 Markdown 中直接使用 React/Vue 组件。

### 内置组件

#### Counter 计数器组件

```mdx
import Counter from '../components/Counter.vue';

<Counter initialCount={0} />

TypstBlock 数学公式

import TypstBlock from '../components/TypstBlock.astro';

<TypstBlock code={`
  $ f(x) = x^2 + 2x + 1 $
`} />

自定义组件

您可以在 src/components/ 目录下创建自己的组件：

<!-- src/components/MyButton.vue -->
<template>
  <button class="my-btn" @click="handleClick">
    <slot />
  </button>
</template>

<script setup>
const handleClick = () => {
  console.log('Button clicked!');
};
</script>

<style scoped>
.my-btn {
  padding: 0.5rem 1rem;
  background: linear-gradient(135deg, #3b82f6, #2563eb);
  color: white;
  border: none;
  border-radius: 0.5rem;
  cursor: pointer;
}
</style>

然后在文章中使用：

import MyButton from '../components/MyButton.vue';

<MyButton>点击我</MyButton>

组件交互性

使用 client:* 指令控制组件的客户端行为：

指令 说明
client:load 页面加载时立即激活
client:visible 组件进入视口时激活
client:idle 浏览器空闲时激活
client:media 满足媒体查询时激活

示例：

<MyButton client:visible>进入视口时激活</MyButton>

Typst 学术排版

NovaBlog 内置 Typst 支持，可以渲染高质量的数学公式和学术排版。

什么是 Typst？

Typst 是新一代排版系统，具有：

  • 比 LaTeX 更简洁的语法
  • 更快的编译速度
  • 原生支持数学公式

基本用法

import TypstBlock from '../components/TypstBlock.astro';

<TypstBlock code={`
  $ f(x) = integral_0^infinity e^(-x^2) dif x = sqrt(pi) / 2 $
`} />

数学公式示例

积分

$ integral_0^1 x^2 dif x = 1/3 $

求和

$ sum_(i=1)^n i = (n(n+1))/2 $

矩阵

$ A = mat(
  1, 2, 3;
  4, 5, 6;
  7, 8, 9
) $

分数

$ (a + b) / (c + d) $

上下标

$ x_1^2 + x_2^2 = r^2 $

高级排版

Typst 还支持：

  • 多行公式对齐
  • 定理环境
  • 化学方程式
  • 代码高亮

更多语法请参考 Typst 官方文档。

动效 HTML 块

在 MDX 中可以直接使用 HTML 标签和内联样式，创建带动画的内容块。

示例：渐变背景卡片

<div style={{
  padding: '2rem',
  background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
  borderRadius: '1rem',
  color: 'white',
  textAlign: 'center'
}}>
  <h3 style={{ marginBottom: '0.5rem' }}>✨ 特色卡片</h3>
  <p>这是一个带渐变背景的卡片</p>
</div>

示例：CSS 动画

<style>
  .pulse-box {
    animation: pulse 2s infinite;
  }
  
  @keyframes pulse {
    0% { transform: scale(1); opacity: 1; }
    50% { transform: scale(1.05); opacity: 0.8; }
    100% { transform: scale(1); opacity: 1; }
  }
</style>

<div class="pulse-box" style={{
  padding: '1.5rem',
  background: '#3b82f6',
  borderRadius: '0.5rem',
  color: 'white',
  textAlign: 'center'
}}>
  🔔 脉冲动画效果
</div>

示例：悬停效果

<style>
  .hover-card {
    transition: transform 0.3s ease, box-shadow 0.3s ease;
  }
  .hover-card:hover {
    transform: translateY(-5px);
    box-shadow: 0 10px 40px rgba(0, 0, 0, 0.2);
  }
</style>

<div class="hover-card" style={{
  padding: '1.5rem',
  background: 'white',
  borderRadius: '0.5rem',
  boxShadow: '0 2px 10px rgba(0, 0, 0, 0.1)',
  cursor: 'pointer'
}}>
  🖱️ 鼠标悬停试试
</div>

示例：交互式组件

结合 Vue 组件创建交互式内容：

<!-- src/components/InteractiveCard.vue -->
<template>
  <div 
    class="card"
    @click="toggle"
    :style="{ background: isActive ? '#3b82f6' : '#e5e7eb' }"
  >
    <h3>{{ title }}</h3>
    <p>{{ isActive ? '已激活 ✓' : '点击激活' }}</p>
  </div>
</template>

<script setup>
import { ref } from 'vue';

const props = defineProps({
  title: String
});

const isActive = ref(false);
const toggle = () => isActive.value = !isActive.value;
</script>

<style scoped>
.card {
  padding: 1.5rem;
  border-radius: 0.5rem;
  cursor: pointer;
  transition: all 0.3s ease;
  color: white;
}
</style>

评论系统

NovaBlog 内置评论系统，支持多级嵌套回复和 Markdown 语法。

发表评论

  1. 在文章页面滚动到评论区
  2. 点击登录按钮进行用户认证
  3. 输入评论内容（支持 Markdown）
  4. 点击发送

回复评论

  1. 点击评论下方的"回复"按钮
  2. 输入回复内容
  3. 提交后将显示在原评论下方

Markdown 支持

评论区支持基础 Markdown 语法：

语法 效果
**粗体** 粗体
*斜体* 斜体
`代码` 代码
[链接](url) 链接
> 引用 引用块

删除评论

用户可以删除自己发表的评论。管理员可以删除任何评论。

用户注册与登录

注册账号

  1. 点击页面右上角的"登录"按钮
  2. 在登录弹窗中点击"注册"
  3. 填写用户名、邮箱和密码
  4. 提交注册

登录账号

支持两种登录方式：

  • 用户名 + 密码
  • 邮箱 + 密码

用户角色

角色 权限
user 发表评论、删除自己的评论
admin 所有权限 + 删除任意评论

修改个人资料

登录后可以修改：

  • 昵称
  • 头像 URL
  • 个人简介

主题定制

CSS 变量

NovaBlog 使用 CSS 变量实现主题系统，可在 src/styles/global.css 中修改：

:root {
  /* 主色调 */
  --color-primary-50: #eff6ff;
  --color-primary-100: #dbeafe;
  --color-primary-500: #3b82f6;
  --color-primary-600: #2563eb;
  
  /* 背景色 */
  --color-background: #ffffff;
  --color-muted: #f3f4f6;
  
  /* 文字色 */
  --color-foreground: #1f2937;
  --color-muted-foreground: #6b7280;
  
  /* 边框色 */
  --color-border: #e5e7eb;
}

暗色主题

修改 CSS 变量实现暗色模式：

.dark {
  --color-background: #1a1a2e;
  --color-foreground: #eaeaea;
  --color-muted: #16213e;
  --color-border: #0f3460;
}

Tailwind 配置

在 tailwind.config.mjs 中自定义主题：

export default {
  theme: {
    extend: {
      colors: {
        primary: {
          50: '#eff6ff',
          // ... 更多颜色
        }
      },
      fontFamily: {
        sans: ['Inter', 'sans-serif'],
      }
    }
  }
}

布局组件

主要布局文件：

  • src/layouts/BaseLayout.astro - 基础布局（Header/Footer）
  • src/layouts/PostLayout.astro - 文章布局（目录/评论）

附件管理

图片存放位置

将图片放在 public/images/ 目录下：

public/
├── images/
│   ├── posts/
│   │   ├── hello-world.jpg
│   │   └── tutorial-cover.png
│   └── avatars/
│       └── default.png

在文章中引用

![图片描述](/images/posts/hello-world.jpg)

在 Frontmatter 中使用封面图

---
heroImage: /images/posts/my-cover.jpg
heroAlt: 这是一张封面图
---

其他附件

PDF、ZIP 等文件也放在 public/ 目录：

public/
├── downloads/
│   └── source-code.zip
└── documents/
    └── paper.pdf

引用方式：

[下载源码](/downloads/source-code.zip)
[查看论文](/documents/paper.pdf)

图片优化建议

  • 使用 WebP 格式减少文件大小
  • 封面图推荐尺寸：1920x1080
  • 文章内图片推荐宽度：800px
  • 压缩工具：Squoosh

常见问题

Q: 文章修改后没有更新？

A: 开发模式下 Astro 会自动热重载。如果生产构建，需要重新运行 npm run build。

Q: Typst 公式渲染失败？

A: 确保 Typst 已正确安装。运行 typst --version 检查。

Q: 评论无法发送？

A: 检查后端服务是否正常运行在 localhost:8080。

Q: 如何修改站点信息？

A: 编辑 src/layouts/BaseLayout.astro 和 astro.config.mjs 中的站点配置。

Q: 如何添加 Google Analytics？

A: 在 src/layouts/BaseLayout.astro 的 <head> 中添加 GA 脚本。

获取帮助

  • 📖 查看 开发文档 了解技术细节
  • 🐛 提交 Issue 反馈问题
  • 💬 在 GitHub Discussions 中讨论
Reference in New Issue View Git Blame Copy Permalink