博文写作规范和工具推荐

写作设置

1
title: "博文写作规范和工具推荐"; //标题
2
description: "规范和工具可以提升效率"; //描述
3
pubDate: "2025-12-20"; //发表时间
4
updatedDate: "2025-12-10"; //更新时间
5
heroImage: ""; //封面图片
6
categories: ["tutorial"]; //分类
7
tags: ["spec", "tools"]; //标签

标题和描述

标题和描述会展示在文章详情页和部分目录页中

发布和更新时间

发布时间

必填发布时间，展示在文章详情页标题下方和部分目录页中，归档页根据时间进行年度归档

更新时间

更新文章后，可填写更新时间，检测到当前文章有更新时间后，文章底部会有小字提示，提示文章最后更新于“更新时间”

分类和标签

分类是一类文章的聚合，例如，针对一个大类，可能有“教程”、“生活”、“笔记”等分类，他们彼此间的关联性较低

标签是具体文章的特色，例如，可能有“工具”、“规范”等标签，他们彼此间的关联性较高

文章结构

• 最多使用三层结构，起头标题使用 H2，子节点使用 H3
• 多使用 Q/A 结构，方便答疑解惑

图片

图片时文章或教程的重要展示部分，相较于枯燥的文本，可以通过视觉展示更重要的信息

图片的存储

图片存储在当前文章目录下的 img 目录下，

结构如下：

1
src/content/blog/hello-world/index.md
2
src/content/blog/hello-world/images/cover.png
3
src/content/blog/hello-world/images/step-1.webp

优点：文章迁移/复制最方便，不会找不到图。

部份较大的文件，例如高清图片、视频等，存放在 OSS 并使用链接引用

存储规则

1. 文章内的截图/配图：先本地存（跟文章走）
2. 大图/视频封面/高频访问资源：放 OSS/CDN
3. 全站通用（logo、头像、社交卡模板等）：放 src/assets 或 public

格式控制

1. 能用 WebP/AVIF 就用（体积小很多）
2. 截图尽量别用 PNG（除非确实需要无损），优先 WebP
3. 博客封面固定比例（比如 1200×630 或 16:9），避免布局抖动
4. 命名统一：cover.webp, step-1.webp, diagram-auth-flow.webp
5. 文章目录里图片别用中文/空格（跨平台和 URL 更稳）

本地存的优势

享受下述优势：

• 图片量不大（几百张以内）
• 你希望文章和图片“天然一致”（迁移、备份、回滚都简单）
• 你用 Git 管理内容，想一条命令就能全站跑起来
• 你想用 Astro 的图片优化能力（生成多尺寸、压缩等）

OSS 的选择

优势:

• 图片很多、仓库不想膨胀
• 你希望图片独立于站点发布（内容换前端框架也不搬图）
• 你想要 CDN 加速、跨地域访问稳定
• 你已经有对象存储（阿里 OSS / 腾讯 COS / 七牛 / Cloudflare R2 等）

劣势：

• 内容可迁移性下降（换桶/换域名要批量替换）
• 图片优化要靠 OSS 的处理能力或你自己预处理
• 需要管权限/防盗链/域名/HTTPS（不过一旦配好就很省心）

图片的处理

图片的使用

写作工具

Markdown 写作语法

参考下方链接

基本语法

白板图

使用白板图，可快速流程式记录想法

白板图

流程图

已建立美人鱼流程图支持

Mermaid Chart