如何借助mkdocs/mkdocstrings自动添加GitHub源码跳转链接？

API 探路者

2026-7-27

用mkdocstrings自动添加GitHub源码跳转链接（含行号）

完全可以通过::: identifier语法实现类似SciPy文档的[source]按钮效果，具体步骤如下：

基础配置开启源码链接
在mkdocs.yml中配置mkdocstrings的Python处理器，指定仓库地址和代码目录，同时开启显示源码选项：
```
plugins:
  - mkdocstrings:
      default_handler: python
      handlers:
        python:
          options:
            show_source: true
            repo_url: https://github.com/你的用户名/你的仓库名
            repo_dir: src/  # 替换为你的代码实际所在目录，根目录可留空
```
配置后，使用::: your.module.Class或::: your.module.function语法生成文档时，会自动在标题旁添加指向GitHub对应源码（含行号）的链接。

自定义样式贴近SciPy效果
默认的源码链接样式可能不符合需求，可通过自定义模板和CSS调整：

创建自定义模板文件，比如docs/templates/mkdocstrings/python/function.html（类的模板对应class.html），修改标题部分为：
```
<h2 id="{{ id }}">{{ name }}<a href="{{ source_url }}" class="source-link" target="_blank">[source]</a></h2>
```

在mkdocs.yml中指定模板目录：

plugins:
  - mkdocstrings:
      default_handler: python
      handlers:
        python:
          options:
            template_dir: docs/templates/mkdocstrings/python

添加自定义CSS（比如docs/css/custom.css）美化按钮样式：

.source-link {
  float: right;
  font-size: 0.8em;
  text-decoration: none;
  background-color: #f5f5f5;
  padding: 2px 8px;
  border-radius: 4px;
  color: #404040;
}
.source-link:hover {
  background-color: #e8e8e8;
}