MkDocs 搭建的网站如何做 SEO 优化？

MkDocs 本身只是一个 静态文档生成器，并没有内建 SEO 功能，但结合 MkDocs-Material 和一些插件/配置，可以做比较完整的 SEO 优化。下面给你一份系统的方案。

1. 基础配置优化（mkdocs.yml）

在 mkdocs.yml 中设置以下内容：

site_name: Material for MkDocs
site_description: "MkDocs 的一个现代化主题，专注于优雅的文档体验"
site_author: "Martin Donath"
site_url: "https://squidfunk.github.io/mkdocs-material/"

作用：

• site_name → 网页 <title>

• site_description → <meta name=”description”>

• site_author → <meta name=”author”>

• site_url → 生成 canonical URL，避免重复收录。

2. 页面级元信息

每个文档文件可以在 YAML front matter 中定义 SEO 元信息，例如：

---
title: 入门指南
description: 本文档介绍如何安装并快速上手 Material for MkDocs。
keywords: [mkdocs, material, 入门, 教程]
---

生成 <title> 与 <meta> 标签，帮助搜索引擎理解页面主题。

3. Sitemap 与 robots.txt

安装 sitemap 插件

pip install mkdocs-sitemap-plugin

配置

plugins:
  - search
  - sitemap:
      changefreq: daily
      priority: 0.5

添加 robots.txt

在 docs/robots.txt 中写入：

User-agent: *
Allow: /

Sitemap: https://squidfunk.github.io/mkdocs-material/sitemap.xml

帮助搜索引擎发现并收录页面。

4. URL 与站点结构优化

使用语义化 URL：

例如 /getting-started/ 优于 /docs/page1/

保持导航清晰：

在 mkdocs.yml 中定义 nav:，让搜索引擎能爬取完整的层次结构。

5. 提升页面内容质量

搜索引擎更重视内容而非配置，因此要保证：

• 合理使用标题（# H1, ## H2）进行分层。

• 图片加 alt 属性，例如：

![Material for MkDocs Logo](assets/images/logo.png)

• 内容聚焦一个主题，避免一页写太多无关内容。

• 多使用表格、列表、代码块，增加结构化内容。

6. 页面增强（Open Graph & Social Cards）

Material 内置了 Open Graph 支持，可以在 mkdocs.yml 中配置：

extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/squidfunk/mkdocs-material
    - icon: fontawesome/brands/twitter
      link: https://twitter.com/squidfunk

生成分享卡片，提升在社交媒体上的可见度。

7. 添加 Schema.org 标记

参考： https://github.com/ultralytics/mkdocs

pip install mkdocs-ultralytics-plugin

plugins:
  - ultralytics:
      verbose: True
      enabled: True
      default_image: "https://www.ultralytics.com/images/social.png" # Example default image
      default_author: "git@ultralytics.com" # Example default author
      add_desc: True
      add_image: True
      add_keywords: True
      add_share_buttons: True
      add_authors: True # Disabled by default
      add_json_ld: True # Disabled by default
      add_css: True

验证:

配置好后，去 Google 的 Rich Results Test
或 Schema.org Validator 测试，确认没有报错。

8. 性能优化

搜索引擎也会参考页面加载速度。推荐插件：

pip install mkdocs-minify-plugin mkdocs-gzip-plugin

配置：

plugins:
  - search
  - minify:
      minify_html: true
  - gzip

9. 分析与追踪

在 mkdocs.yml 添加 Google Analytics（或其他分析工具）：

extra:
  analytics:
    provider: google
    property: G-XXXXXXXXXX

10. 重定向与旧链接维护

如果文档结构调整，建议安装：

pip install mkdocs-redirects

配置：

plugins:
  - redirects:
      redirect_maps:
        old-page.md: new-page.md

避免 404 错误，保留搜索引擎已有收录。

11. 总结

本文以 Material for MkDocs 为例，一个良好的 SEO 优化流程是：

1. 在 mkdocs.yml 填写基础信息（site_name, site_url, site_description）。

2. 每个文档添加 title 和 description。

3. 使用 sitemap.xml 和 robots.txt 辅助收录。

4. 保持 URL 语义化和清晰的导航结构。

5. 提升文档内容质量，图片加 alt。

6. 配置 Open Graph 与 social 卡片，增强社交分享。

7. 用 minify/gzip 提升速度。

8. 加入分析追踪，优化 SEO 效果。

9. 使用 redirects 管理旧链接，防止流量流失。

参考文档

MkDocs sitemap.xml file generation