MKDocs Material中俄文锚点无法滚动到对应标题的问题

问题原因 #

Obsidian生成的锚点链接直接使用原俄文字符，而MKDocs默认的toc扩展会将非ASCII标题转成ASCII化的slug（移除或转义俄文字符），导致链接的href与目标标题的id不匹配，无法触发滚动和高亮。

解决方案 #

方案1：使用PyMdown Extensions的Unicode兼容slug生成 #

1. 安装PyMdown扩展包：

pip install pymdown-extensions

2. 修改mkdocs.yml的markdown_extensions配置，替换默认slug规则为支持Unicode的uslugify：

theme:
  name: material
  features:
    - navigation.instant
    - navigation.tabs
plugins:
  - search
markdown_extensions:
  - pymdownx.slugs:
      slugify: !!python/name:pymdownx.slugs.uslugify
      case: lower
  - toc:
      permalink: "#"
      slugify: !!python/name:pymdownx.slugs.uslugify

方案2：自定义Obsidian兼容的slug生成函数 #

如果不想依赖第三方扩展，可以自定义slug函数匹配Obsidian的行为：

1. 在项目根目录创建slugify.py文件，写入以下代码：

import re
from unicodedata import normalize

def obsidian_slugify(text):
    # 复刻Obsidian的slug规则：转小写、空格替换为-、保留俄文等Unicode字符
    text = normalize('NFKC', text)
    text = text.lower()
    text = re.sub(r'\s+', '-', text)
    text = re.sub(r'[^\w\-]', '', text)
    return text

2. 修改mkdocs.yml的toc扩展配置，使用自定义函数：

theme:
  name: material
  features:
    - navigation.instant
    - navigation.tabs
plugins:
  - search
markdown_extensions:
  - toc:
      permalink: "#"
      slugify: !!python/name:slugify.obsidian_slugify

验证方法 #

生成站点后，检查目标页面中对应俄文标题的id属性，确认其与链接中的锚点字符串完全一致（比如наследование-доступов-в-дереве-отделов），此时点击链接即可正常滚动并高亮目标标题。

内容的提问来源于stack exchange，提问作者NikBulatov