单文件方案#

这是在 Twilight 博客系统中创建文章的两种方法之一。该方法适用于简单文章，并且不需要管理大量图片资源的情况。

⚠️ 注意
单文件方案会导致 RSS 无法正常构建本地图片路径。
如果你使用图床则没有问题。
若你需要 RSS 功能，请使用 文件夹写作方案。

创建文章#

在 src/content/posts 目录下创建一个新的 Markdown 文件，文件名应具有描述性，例如：

1
my-first-post.md

在文件中添加 frontmatter（前置元数据），必须包含 title 和 description 字段：

1
---
2
title: Markdown Tutorial
3
published: 2025-01-20
4
pinned: true
5
description: A simple example of a Markdown blog post.
6
tags: [Markdown, Blogging]
7
category: Examples
8
licenseName: "Unlicensed"
9
author: emn178
10
sourceLink: "https://github.com/emn178/markdown"
11
draft: false
12
date: 2025-01-20
13
image:
14
  url: 'https://example.com/image.jpg'
15
  alt: '图片描述'
16
pubDate: 2025-01-20
17
---

Frontmatter 字段详解#

frontmatter 支持的字段包括：

必需字段#

title：文章标题
description：文章描述

发布相关#

published：发布日期（YYYY-MM-DD）
pubDate：发布日期（与 published 类似）
date：文章创建日期
draft：是否为草稿（true 草稿 / false 发布）

内容分类#

tags：标签数组
category：文章分类
pinned：是否置顶文章

作者信息#

author：作者姓名
licenseName：许可证名称（如 MIT、CC BY 4.0）
sourceLink：源链接（如 GitHub 仓库）

图片设置#

image：文章封面图片
- url：图片地址
- alt：替代文本

⚠️ 单文件方案会导致 RSS 无法正确构建本地图片路径。

Markdown 学习资源#

如果你不熟悉 Markdown，推荐先学习基础语法：

📚 菜鸟教程 - Markdown 教程

教程内容包括：

基本语法
标题、段落、换行
粗体、斜体
列表、链接、图片
代码块、表格
高级功能

掌握这些即可轻松编写美观的博客文章。

Frontmatter 最佳实践#

日期格式#

建议使用 ISO 8601：

1
published: 2025-01-20
2
date: 2025-01-20
3
pubDate: 2025-01-20

标签与分类#

标签应具体且相关
分类通常更宽泛

示例：

1
tags: [Vue.js, JavaScript, Frontend, Tutorial]
2
category: Web Development

草稿管理#

1
draft: true   # 不会在生产环境显示
2
draft: false  # 正常发布

许可证设置#

常见许可证：

MIT
Apache-2.0
CC BY 4.0
CC BY-SA 4.0
Unlicensed

完整示例#

1
---
2
title: "Vue.js 3 组合式API完全指南"
3
published: 2025-01-20
4
pinned: false
5
description: "深入了解Vue.js 3的组合式API，包括setup函数、响应式系统和生命周期钩子。"
6
tags: [Vue.js, JavaScript, Frontend, API]
7
category: "Web Development"
8
licenseName: "CC BY 4.0"
9
author: "张三"
10
sourceLink: "https://github.com/zhangsan/vue3-guide"
11
draft: false
12
date: 2025-01-20
13
image:
14
  url: 'https://example.com/vue3-cover.jpg'
15
  alt: 'Vue.js 3 组合式API指南封面'
16
pubDate: 2025-01-20
17

18
# Vue.js 3 组合式API完全指南
19

20
在这篇文章中，我们将深入探讨 Vue.js 3 的组合式 API...
21
---

预览文章#

保存文件后，在浏览器中访问：

1
http://localhost:4321/posts/my-first-post

若文件不存在或命名错误，将显示 404。

链接到文章#

1
<a href="/posts/my-first-post/">我的第一篇文章</a>

添加图片#

将图片放在 public/images 下：

1
![图片描述](/images/my-image.png)

创建多篇文章#

1
src/content/posts/
2
├── my-first-post.md
3
├── my-second-post.md
4
└── my-third-post.md

链接多篇文章#

1
<ul>
2
  <li><a href="/posts/my-first-post/">我的第一篇文章</a></li>
3
  <li><a href="/posts/my-second-post/">我的第二篇文章</a></li>
4
  <li><a href="/posts/my-third-post/">我的第三篇文章</a></li>
5
</ul>

注意事项#

文件名会作为 URL 路径，应简洁且无特殊字符
date 字段可选，不写则使用文件创建时间
单文件方案适合简单文章；大量图片请使用文件夹方案

致虚以守静