SEO 配置指南
本文档说明 mdView 文档系统的 SEO 策略、配置方式与最佳实践。
概述
mdView 为每一篇文档自动生成完整的 SEO 元数据，包括标题、描述、关键词、Open Graph 标签、Twitter Card、规范链接（canonical URL）以及 JSON-LD 结构化数据。系统采用四级 fallback 策略，确保即使文档不包含任何 SEO 配置也能生成合理的元数据。
Fallback 策略
Frontmatter（优先）
↓ 未配置
文档正文约定段落（## 概述 / ## 关键词）
↓ 无匹配段落
文档内容自动提取（首段 / 各级标题）
↓ 内容为空
系统 settings 表参数
↓ 未设置
硬编码默认值
方式一：Frontmatter（推荐）
在文档顶部使用 YAML frontmatter 精确控制 SEO 信息。
---
title: 前端编译指南
description: Node.js 与 Gulp 前端构建环境搭建指南
keywords: nodejs,gulp,npm,前端编译,构建工具
---
# 正文标题
正文内容...
支持的 frontmatter 字段
Frontmatter 格式要求
--- 开始，以 --- 结束key: value 语法[item1, item2]方式二：文档正文约定
在文档中使用特定的二级标题段落声明 SEO 信息。
概述段（description）
## 概述
本文档介绍了 XXX 的安装和配置方法，包含常见问题的解决方案。
系统会提取 ## 概述 标题后的第一段内容作为页面描述。描述限制在 160 个字符以内。
关键词段（keywords）
## 关键词
- nodejs
- gulp
- npm
- 前端编译
- 构建工具
系统会提取列表项作为关键词，最多 8 个。支持以下列表格式：
- 关键词1
- 关键词2
或：
- 关键词1, 关键词2, 关键词3
方式三：系统 settings 参数
当文档未配置 frontmatter 也无约定段落时，系统从 settings 表读取全局默认值。
管理员可在后台系统配置中设置这些参数。
自动生成的结构化数据
规范链接（Canonical URL）
每个页面自动生成规范 URL，格式为：
https://<域名>/<文档路径>
例如文档 intro.md 的规范链接为 https://docs.example.com/intro。
JSON-LD
系统自动输出两种 Schema 类型的 JSON-LD 结构化数据：
示例输出：
{
"@context": "https://schema.org",
"@graph": [
{
"@type": "BreadcrumbList",
"itemListElement": [
{
"@type": "ListItem",
"position": 1,
"name": "首页",
"item": "https://example.com/vitep/"
},
{
"@type": "ListItem",
"position": 2,
"name": "guide",
"item": "https://example.com/vitep/"
}
]
},
{
"@type": "TechArticle",
"headline": "SEO 配置指南",
"description": "本文档说明 mdView 文档系统的 SEO 策略...",
"url": "https://example.com/vitep/guide/seo",
"inLanguage": "zh-CN"
}
]
}
Open Graph / Twitter Card
每个页面自动输出以下社交分享标签：
<meta property="og:title" content="SEO 配置指南 | mdView 文档">
<meta property="og:description" content="本文档说明 mdView 文档系统的 SEO 策略...">
<meta property="og:type" content="article">
<meta property="og:url" content="https://example.com/vitep/guide/seo">
<meta property="og:site_name" content="mdView 文档">
<meta property="og:locale" content="zh_CN">
<meta name="twitter:card" content="summary">
<meta name="twitter:title" content="SEO 配置指南 | mdView 文档">
<meta name="twitter:description" content="本文档说明 mdView 文档系统的 SEO 策略...">
面包屑导航
系统根据文档树自动生成面包屑导航，显示在文章顶部。
面包屑结构：首页 / 父级目录 / 当前页面
示例效果：
首页 / guide / SEO 配置指南
最佳实践
1. 优先使用 Frontmatter
最精确的控制方式，推荐所有重要文档添加 frontmatter：
---
title: API 接口文档
description: mdView 系统所有 RESTful API 接口的详细说明
keywords: api,rest,接口,认证,文档
---
2. 描述长度控制
描述信息应控制在 150-160 个字符以内。系统会自动截断超长描述。
3. 关键词数量
关键词建议控制在 5-8 个，以逗号分隔。每个关键词应为 2-8 个字符的精准词汇。
4. 标题唯一性
每个文档的 title 应与站点内其他文档区分，避免搜索引擎判定为重复内容。
5. 概述段的写法
概述段应概括文档的核心内容，前 160 字包含关键信息。避免在概述中使用格式标记（加粗、链接等），系统会自动清理。