Twilight 博客完全指南：从入门到精通#

欢迎使用 Twilight 博客模板！本指南将带你全面了解如何高效地撰写博客文章。

一、快速开始#

1.1 创建新文章#

有两种方式创建新文章：

1
# 方式一：使用命令行
2
pnpm new-post my-first-blog
3

4
# 方式二：手动创建
5
# 在 src/content/posts/ 目录下创建 .md 文件

1.2 文章 Frontmatter 详解#

1
---
2
title: "文章标题"           # 必需：文章标题
3
published: 2026-03-16     # 必需：发布日期
4
updated: 2026-03-17       # 可选：更新日期
5
description: "文章描述"    # 必需：SEO 描述
6
tags: [标签1, 标签2]       # 可选：标签数组
7
category: "教程"           # 可选：分类
8
pinned: false             # 可选：是否置顶
9
draft: false              # 可选：是否为草稿
10
author: "作者名"          # 可选：作者
11
cover: "/path/to.jpg"    # 可选：封面图
12
coverInContent: false    # 可选：是否在内容中显示封面
13
comment: true            # 可选：是否开启评论
14
encrypted: false         # 可选：是否加密
15
password: ""              # 可选：访问密码
16
---

二、编写优质博客的技巧#

2.1 内容结构#

1
# 使用多级标题组织内容
2

3
## 一级标题 - 大章节
4
### 二级标题 - 小节
5
#### 三级标题 - 详细内容

2.2 代码块#

支持多种编程语言：

1
// JavaScript 示例
2
function greet(name) {
3
    return `Hello, ${name}!`;
4
}
5

6
const result = greet("Twilight");
7
console.log(result);

1
# Python 示例
2
def fibonacci(n):
3
    if n <= 1:
4
        return n
5
    return fibonacci(n-1) + fibonacci(n-2)
6

7
print(fibonacci(10))

1
// TypeScript 示例
2
interface BlogPost {
3
    title: string;
4
    published: Date;
5
    tags: string[];
6
}
7

8
function createPost(data: BlogPost): BlogPost {
9
    return { ...data, published: new Date() };
10
}

三、Mermaid 图表#

Twilight 内置支持 Mermaid 图表，可以绘制多种图形。

3.1 流程图#

graph TD A[开始] --> B{是否有内容?} B -->|有| C[编写内容] B -->|没有| D[寻找灵感] D --> C C --> E[添加图表] E --> F[预览效果] F --> G[发布文章] G --> H[结束] style A fill:#f9f,stroke:#333 style G fill:#9f9,stroke:#333 style H fill:#ff9,stroke:#333

3.2 序列图#

sequenceDiagram participant 作者 participant 编辑器 participant GitHub participant 读者作者->>编辑器: 编写博客编辑器->>GitHub: 提交代码 GitHub-->>编辑器: 触发构建编辑器-->>读者: 自动部署读者->>编辑器: 阅读文章编辑器-->>作者: 收到反馈

3.3 状态图#

stateDiagram-v2 [*] --> 草稿草稿 --> 编辑中: 开始编辑编辑中 --> 待审核: 提交审核待审核 --> 发布: 审核通过待审核 --> 草稿: 审核拒绝发布 --> 已发布: 上线已发布 --> [*] 状态1: 草稿状态2: 编辑中状态3: 待审核状态4: 发布

3.4 类图#

classDiagram class BlogPost { +string title +Date published +string description +string[] tags +string category +boolean pinned +boolean draft +getTitle() +setTitle(title) +isPublished() } class Author { +string name +string email +Post[] posts +createPost() } class Category { +string name +Post[] posts } BlogPost "1" --> "1" Author BlogPost "1" --> "1" Category

3.5 甘特图#

gantt title 博客开发计划 dateFormat YYYY-MM-DD section 规划确定主题 :a1, 2026-03-01, 3d 收集资料 :after a1, 5d section 写作撰写初稿 :2026-03-05, 7d 完善内容 :2026-03-12, 5d section 发布校对审核 :2026-03-17, 3d 正式发布 :2026-03-20, 1d

3.6 饼图#

pie title 博客内容分布 "技术教程" : 40 "生活随笔" : 25 "读书笔记" : 20 "项目展示" : 15

3.7 ER 图#

erDiagram POST ||--o{ COMMENT : has POST ||--o{ TAG : has POST }|..|| CATEGORY : belongs AUTHOR ||--o{ POST : writes POST { string id string title text content date published boolean draft } COMMENT { string id text content date created }

四、数学公式#

4.1 行内公式#

行内公式如 $E = mc^2$ 或 $\sum_{i=1}^{n} i = \frac{n(n+1)}{2}$

4.2 块级公式#

f(x) = \int_{-\infty}^{\infty} \hat{f}(\xi) e^{2\pi i \xi x} d\xi

\begin{pmatrix} a_{11} & a_{12} \\ a_{21} & a_{22} \end{pmatrix} \cdot \begin{pmatrix} x \\ y \end{pmatrix} = \begin{pmatrix} b_1 \\ b_2 \end{pmatrix}

五、API 调用示例#

5.1 获取文章列表#

1
import { getCollection } from "astro:content";
2

3
const posts = await getCollection("posts", ({ data }) => {
4
    return data.draft !== true; // 过滤草稿
5
});
6

7
// 按日期排序
8
const sortedPosts = posts.sort((a, b) => {
9
    return new Date(b.data.published).getTime() -
10
           new Date(a.data.published).getTime();
11
});

5.2 获取分类和标签#

1
import { getCollection } from "astro:content";
2

3
// 获取所有标签
4
const allPosts = await getCollection("posts");
5
const tags = [...new Set(allPosts.flatMap(post => post.data.tags))];
6

7
// 获取所有分类
8
const categories = [...new Set(
9
    allPosts.map(post => post.data.category).filter(Boolean)
10
)];

5.3 分页实现#

1
const PAGE_SIZE = 10;
2
const totalPosts = await getCollection("posts");
3
const totalPages = Math.ceil(totalPosts.length / PAGE_SIZE);
4

5
function getPagePosts(page: number, posts: any[]) {
6
    const start = (page - 1) * PAGE_SIZE;
7
    return posts.slice(start, start + PAGE_SIZE);
8
}

六、常用组件#

6.1 按钮链接#

1
---
2
import ButtonLink from "@components/common/buttonLink.astro";
3
---
4

5
<ButtonLink
6
    href="/posts/my-first-blog"
7
    icon="material-symbols:article"
8
    text="阅读全文"
9
/>

6.2 图标使用#

1
---
2
import Icon from "@components/common/icon.astro";
3
---
4

5
<Icon icon="fa6-solid:code" class="w-5 h-5" />
6
<Icon icon="mdi:github" class="w-6 h-6" />

七、高级技巧#

7.1 嵌入音乐#

1
:::music
2
{
3
    "server": "netease",
4
    "type": "song",
5
    "id": "12345678"
6
}
7
:::
8

9
### 7.2 嵌入 GitHub 项目
10

11
```markdown
12
:::github
13
{
14
    "user": "Spr-Aachen",
15
    "repo": "Twilight",
16
    "height": 400
17
}
18
:::

7.3 加密文章#

1
---
2
encrypted: true
3
password: "mypassword"
4
---

八、写作最佳实践#

8.1 标题优化#

使用清晰、描述性的标题
包含关键词但避免关键词堆砌
控制在 60 字符以内

8.2 内容结构#

1
1. 引言 - 介绍文章主题
2
2. 背景 - 提供必要上下文
3
3. 主体 - 详细讲解核心内容
4
4. 实践 - 提供代码示例
5
5. 总结 - 回顾要点
6
6. 参考 - 列出参考文献

8.3 SEO 优化#

每篇文章都要有独特的 description
使用相关标签（3-5 个为宜）
添加合适的分类

九、总结#

Twilight 博客系统提供了丰富的功能：

✅ Mermaid 图表支持
✅ 数学公式渲染
✅ 代码高亮
✅ 评论系统
✅ 文章加密
✅ 标签和分类
✅ 搜索功能
✅ 响应式设计

希望这份指南能帮助你更好地使用 Twilight 书写博客！

Happy Writing! 📝

JJZBQA