Skip to main content

CLAUDE

· 5 min read

根目录 > blog

模块职责​

blog 模块负责管理博客文章内容、作者信息和标签系统。支持 MDX 格式的富文本内容创作，提供完整的博客功能包括文章列表、详情页、作者页面和标签页面。

入口与启动​

主要配置文件​

  • 作者配置: authors.yml - 博客作者信息和社交链接
  • 标签配置: tags.yml - 博客标签定义和描述
  • 文章文件: *.md 和 *.mdx - 博客文章内容

博客目录结构​

blog/
├── authors.yml                 # 全局作者配置
├── tags.yml                   # 全局标签配置
├── 2019-05-28-first-blog-post.md
├── 2019-05-29-long-blog-post.md
├── 2021-08-01-mdx-blog-post.mdx
└── 2021-08-26-welcome/
    ├── index.md              # 欢迎文章
    └── docusaurus-plushie-banner.jpeg  # 文章配图

对外接口​

文章 Front Matter 接口​

---
slug: article-slug            # URL 友好标识符
title: 文章标题
authors: [author1, author2]   # 作者列表
tags: [tag1, tag2]           # 标签列表
date: 2023-12-01             # 发布日期
last_update:                 # 最后更新日期
draft: false                 # 是否草稿
description: 文章描述        # SEO 描述
image: /img/cover.jpg        # 封面图片
---

<!-- truncate -->  # 摘要截断标记

作者配置接口​

author_key:
  name: 作者姓名
  title: 职位/头衔
  url: https://author-website.com
  image_url: https://github.com/avatar.png
  page: true/false           # 是否生成作者页面
  socials:
    x: twitter_handle
    github: github_username
    linkedin: linkedin_url
    newsletter: newsletter_url

标签配置接口​

tag_key:
  label: 显示名称
  permalink: /tag-url        # 标签页面 URL
  description: 标签描述      # SEO 描述

关键依赖与配置​

Docusaurus 博客插件​

  • @docusaurus/plugin-content-blog - 博客内容处理
  • 自动生成文章列表和标签页
  • RSS/Atom 订阅支持
  • 阅读时间计算
  • 相关文章推荐

内容格式支持​

  • Markdown: 标准博客文章格式
  • MDX: 支持 React 组件的富文本
  • 图片处理: 自动优化和响应式
  • 代码高亮: 内置语法高亮支持

SEO 和社交功能​

  • Open Graph 标签支持
  • Twitter Card 集成
  • 结构化数据 (JSON-LD)
  • 社交分享优化

数据模型​

文章数据结构​

interface BlogPost {
  slug: string;
  title: string;
  authors: Author[];
  tags: Tag[];
  date: string;
  last_update?: string;
  content: string;
  excerpt?: string;
  frontMatter: Record<string, any>;
  readingTime?: number;
}

作者数据结构​

interface Author {
  key: string;
  name: string;
  title?: string;
  url?: string;
  image_url?: string;
  page?: boolean;
  socials?: {
    x?: string;
    github?: string;
    linkedin?: string;
    newsletter?: string;
  };
}

标签数据结构​

interface Tag {
  key: string;
  label: string;
  permalink: string;
  description?: string;
  count?: number;  // 文章数量
}

测试与质量​

内容质量检查​

  • 元数据验证: Front Matter 完整性
  • 链接检查: 内外部链接有效性
  • 图片优化: 文件大小和格式检查
  • SEO 优化: 标题、描述、标签检查

性能优化​

  • 图片懒加载
  • 文章摘要生成
  • 分页性能优化
  • 缓存策略配置

用户体验测试​

  • 文章列表导航
  • 搜索功能测试
  • 移动端适配
  • 加载性能测试

常见问题 (FAQ)​

Q: 如何设置文章发布日期？​

A: 在 Front Matter 中设置 date 字段，格式为 YYYY-MM-DD。

Q: 如何让文章在列表中显示摘要？​

A: 在文章中插入 <!-- truncate --> 注释，之前的内容将作为摘要显示。

Q: 如何添加新的作者？​

A: 在 authors.yml 中添加作者配置，然后在文章中引用。

Q: 如何创建带交互性的博客文章？​

A: 使用 .mdx 扩展名，可以在文章中导入和使用 React 组件。

Q: 如何配置 RSS 订阅？​

A: 在 docusaurus.config.ts 的博客配置中设置 feedOptions。

相关文件清单​

配置文件​

  • authors.yml - 全局作者配置
  • tags.yml - 全局标签配置

示例文章​

  • 2019-05-28-first-blog-post.md - 基础博客文章示例
  • 2019-05-29-long-blog-post.md - 长文章示例
  • 2021-08-01-mdx-blog-post.mdx - MDX 文章示例
  • 2021-08-26-welcome/index.md - 带资源文件夹的文章

资源文件​

  • 2021-08-26-welcome/docusaurus-plushie-banner.jpeg - 文章配图

内容创作指南​

文章命名规范​

  • 使用日期前缀：YYYY-MM-DD-title.md
  • 标题使用连字符分隔，小写字母
  • MDX 文件使用 .mdx 扩展名

Front Matter 最佳实践​

  • 必填字段：title, authors, date
  • SEO 优化：填写 description 和 tags
  • 社交分享：设置合适的 image
  • 发布控制：使用 draft 字段管理草稿

内容组织原则​

  • 提供清晰的文章结构
  • 使用适当的标题层级
  • 添加代码示例和截图
  • 保持内容更新和维护

作者和标签管理​

  • 在 authors.yml 中维护作者信息
  • 使用 tags.yml 定义重要标签
  • 文章中引用已配置的作者和标签
  • 定期清理未使用的标签

SEO 和推广优化​

文章 SEO 优化​

  • 使用描述性标题
  • 优化文章摘要
  • 合理使用标签分类
  • 添加内部链接

社交媒体优化​

  • 设置合适的封面图片
  • 优化 Open Graph 标签
  • 配置 Twitter Card
  • 添加社交分享按钮

订阅和分发​

  • 配置 RSS/Atom 订阅
  • 设置邮件订阅集成
  • 优化内容分发策略

变更记录 (Changelog)​

2025-10-25 18:00:53​

  • 创建 blog 模块文档
  • 分析现有博客配置和文章结构
  • 制定内容创作和 SEO 优化指南