文档内容管理

技术文档内容管理系统负责处理项目文档的组织、存储、处理和展示。

内容组织结构

1. 目录结构

文档按功能模块组织在 src/content/docs/ 目录下：

src/content/docs/
├── _meta.json - 根目录结构配置
├── getting-started/ - 快速开始指南
│   ├── _meta.json - 分类结构配置
│   ├── index.mdx - 分类首页
│   └── faq.mdx - 常见问题
├── project/ - 项目介绍文档
├── features/ - 功能模块文档
├── api/ - API接口文档
├── components/ - 组件架构文档
├── content/ - 内容管理文档
├── development/ - 开发指南文档
└── community/ - 社区与贡献文档

2. 元数据配置

通过 _meta.json 文件定义文档结构：

// src/content/docs/_meta.json
{
  "getting-started": {
    "title": "快速开始",
    "description": "从这里开始了解和使用斐流艺创项目"
  },
  "project": {
    "title": "项目介绍",
    "description": "斐流艺创的网站项目介绍"
  }
}

// src/content/docs/getting-started/_meta.json
{
  "index": "快速开始",
  "faq": "常见问题解答"
}

内容格式规范

1. Frontmatter元数据

文档文件包含以下元数据：

---
title: 文档标题
description: 文档简短描述
date: 2025-08-29
update: 2025-08-30
category: 开发指南
tags:
  - 文档
  - 内容管理
---

文档内容...

核心字段

字段名	类型	必需	描述
title	string	是	文档标题
description	string	是	文档简短描述
date	string	是	创建日期 (YYYY-MM-DD格式)
update	string	否	更新日期 (YYYY-MM-DD格式)
category	string	否	文档分类
tags	string[]	否	文档标签列表

2. 内容结构

文档内容遵循以下结构规范：

# 主标题

文档简要介绍。

## 章节标题

章节内容...

### 小节标题

小节内容...

## 总结

文档总结...

内容创作指南

1. 文档结构

• 使用清晰的层级结构
• 保持章节逻辑连贯
• 合理使用列表和代码块
• 添加适当的图表和示例

2. 语言风格

• 使用简洁明了的语言
• 避免过于复杂的句式
• 保持术语一致性
• 提供必要的背景信息

3. 代码示例

```typescript
// 好的示例
function useCounter() {
  const [count, setCount] = useState(0);
  
  const increment = () => setCount(count + 1);
  const decrement = () => setCount(count - 1);
  
  return { count, increment, decrement };
}

使用说明：...

### 4. 链接引用

- 内部链接使用相对路径
- 外部链接添加安全属性
- 提供链接描述文本

```mdx
[快速开始指南](/docs/getting-started)
[Next.js官方文档](https://nextjs.org/docs) <!-- target="_blank" rel="noopener noreferrer" -->

内容处理流程

1. 结构解析

解析文档目录结构：

// src/lib/docs-structure.ts
interface DocsStructure {
  slug: string[];
  title: string;
  description?: string;
  hasIndex: boolean;
  firstDocPath?: string[];
  itemsCount: number;
  items?: DocsStructureItem[];
}

interface DocsStructureItem {
  slug: string[];
  title: string;
  description?: string;
}

export async function generateDocsStructure(): Promise<DocsStructure[]> {
  // 递归扫描文档目录
  // 解析_meta.json配置
  // 生成完整的文档结构树
}

2. 内容读取

读取文档内容文件：

// src/lib/docs-reader.ts
interface DocContent {
  slug: string[];
  title: string;
  description: string;
  date: string;
  content: string;
  tableOfContents: TableOfContentsItem[];
  [key: string]: any;
}

export async function readDocContent(slug: string[]): Promise<DocContent> {
  const filePath = path.join(process.cwd(), 'src/content/docs', ...slug) + '.mdx';
  const fileContent = await fs.readFile(filePath, 'utf-8');
  const { content, data } = matter(fileContent);
  
  // 生成目录结构
  const tableOfContents = generateTableOfContents(content);
  
  return {
    slug,
    content,
    tableOfContents,
    ...data
  } as DocContent;
}

3. 元数据验证

验证文档元数据完整性：

// src/lib/docs-validator.ts
interface DocMetadata {
  title: string;
  description: string;
  date: string;
  update?: string;
  category?: string;
  tags?: string[];
}

export function validateDocMetadata(metadata: any): metadata is DocMetadata {
  // 验证必需字段
  if (!metadata.title || typeof metadata.title !== 'string') {
    throw new Error('Missing or invalid title');
  }
  
  if (!metadata.description || typeof metadata.description !== 'string') {
    throw new Error('Missing or invalid description');
  }
  
  if (!metadata.date || !/^\d{4}-\d{2}-\d{2}$/.test(metadata.date)) {
    throw new Error('Missing or invalid date');
  }
  
  return true;
}

内容API接口

1. 获取文档结构

// src/lib/docs-api.ts
export async function getDocsStructure(): Promise<DocsStructure[]> {
  // 实现获取文档结构逻辑
  // 返回完整的文档导航树
}

2. 获取文档内容

// src/lib/docs-api.ts
interface DocContentDetail extends DocContent {
  prevDoc?: { slug: string[]; title: string };
  nextDoc?: { slug: string[]; title: string };
}

export async function getDocContent(slug: string[]): Promise<DocContentDetail> {
  // 实现获取文档内容逻辑
  // 返回完整文档内容和导航信息
}

内容渲染组件

1. 文档页面组件

// src/features/docs/components/doc-page.tsx
import { DocContent } from './doc-content';
import { DocsSidebar } from './docs-sidebar';
import { TableOfContents } from './table-of-contents';

interface DocPageProps {
  doc: DocContentDetail;
  structure: DocsStructure[];
}

export function DocPage({ doc, structure }: DocPageProps) {
  return (
    <div className="doc-page">
      <DocsSidebar structure={structure} currentSlug={doc.slug} />
      
      <div className="doc-content-wrapper">
        <article className="doc-content">
          <header className="doc-header">
            <h1>{doc.title}</h1>
            <p className="doc-description">{doc.description}</p>
            <div className="doc-meta">
              <time dateTime={doc.date}>创建于 {formatDate(doc.date)}</time>
              {doc.update && (
                <time dateTime={doc.update}>更新于 {formatDate(doc.update)}</time>
              )}
            </div>
          </header>
          
          <DocContent content={doc.content} />
        </article>
        
        {doc.tableOfContents.length > 0 && (
          <TableOfContents items={doc.tableOfContents} />
        )}
      </div>
    </div>
  );
}

2. 侧边栏组件

// src/features/docs/components/docs-sidebar.tsx
interface DocsSidebarProps {
  structure: DocsStructure[];
  currentSlug: string[];
}

export function DocsSidebar({ structure, currentSlug }: DocsSidebarProps) {
  return (
    <nav className="docs-sidebar">
      <ul>
        {structure.map(category => (
          <li key={category.slug.join('-')} className="category">
            <h2>{category.title}</h2>
            <ul>
              {category.items?.map(item => (
                <li 
                  key={item.slug.join('-')} 
                  className={cn('item', {
                    'active': isEqual(item.slug, currentSlug)
                  })}
                >
                  <Link href={`/docs/${item.slug.join('/')}`}>
                    {item.title}
                  </Link>
                </li>
              ))}
            </ul>
          </li>
        ))}
      </ul>
    </nav>
  );
}

内容管理工具

1. 文档创建脚本

快速创建文档模板：

# 创建新的文档
pnpm docs:create "组件设计规范" --category components

# 创建文档分类
pnpm docs:create:category "新分类"

// scripts/create-doc.ts
import fs from 'fs/promises';
import path from 'path';

async function createDoc(title: string, options: { category?: string }) {
  const { category = 'uncategorized' } = options;
  const slug = title.toLowerCase().replace(/\s+/g, '-');
  const fileName = `${slug}.mdx`;
  const filePath = path.join('src/content/docs', category, fileName);
  
  const template = `---
title: ${title}
description: 
date: ${new Date().toISOString().split('T')[0]}
category: ${category}
tags:
  - 
---

# ${title}

`;
  
  await fs.writeFile(filePath, template);
  console.log(`Created document: ${filePath}`);
}

2. 结构检查工具

检查文档结构完整性：

# 检查所有文档结构
pnpm docs:check

# 检查特定分类
pnpm docs:check --category components

// scripts/check-docs.ts
async function checkDocsStructure() {
  // 检查_meta.json文件是否存在
  // 验证slug路径唯一性
  // 检查文档引用完整性
  // 验证导航结构正确性
}

内容SEO优化

1. 元数据生成

为文档生成SEO元数据：

// src/lib/docs-seo.ts
interface DocSEOData {
  title: string;
  description: string;
  url: string;
  type: 'article';
  publishedTime: string;
  updatedTime?: string;
  category?: string;
}

export function generateDocSEOData(doc: DocContentDetail): DocSEOData {
  return {
    title: doc.title,
    description: doc.description,
    url: `/docs/${doc.slug.join('/')}`,
    type: 'article',
    publishedTime: doc.date,
    updatedTime: doc.update,
    category: doc.category
  };
}

2. 面包屑导航

提供文档路径导航：

// src/features/docs/components/breadcrumb.tsx
interface BreadcrumbProps {
  structure: DocsStructure[];
  currentSlug: string[];
}

export function Breadcrumb({ structure, currentSlug }: BreadcrumbProps) {
  // 根据当前slug生成面包屑路径
  const breadcrumbs = generateBreadcrumbs(structure, currentSlug);
  
  return (
    <nav className="breadcrumb" aria-label="面包屑导航">
      <ol>
        <li><Link href="/docs">文档</Link></li>
        {breadcrumbs.map((item, index) => (
          <li key={index}>
            {index < breadcrumbs.length - 1 ? (
              <Link href={`/docs/${item.slug.join('/')}`}>{item.title}</Link>
            ) : (
              <span>{item.title}</span>
            )}
          </li>
        ))}
      </ol>
    </nav>
  );
}

通过这套文档内容管理系统，项目能够有效地组织和管理技术文档，为用户提供清晰、易用的文档浏览体验。