前置知识: Markdown

锚点跳转

3 minIntermediate2026/6/14

Markdown锚点跳转机制：标题锚点、自定义锚点与跨文档链接。

1. 锚点概述

1.1 什么是锚点

锚点是 HTML 中的页面内定位标记，允许通过 URL 的片段标识符（# 后的部分）跳转到页面内的指定位置。

[跳转到安装章节](#安装)

## 安装

安装步骤...

1.2 锚点的工作原理

URL: https://example.com/docs#installation
                              ↑            ↑
                           页面路径      锚点标识符

1. 浏览器加载页面
2. 查找 id="installation" 的元素
3. 滚动到该元素位置

2. 标题自动锚点

2.1 自动生成规则

Markdown 渲染器会自动为标题生成锚点 ID：

## Getting Started → <h2 id="getting-started">

## Hello World! → <h2 id="hello-world">

## API v2.0 → <h2 id="api-v20">

## C++ 编程 → <h2 id="c-编程">

2.2 GitHub 锚点规则

规则输入标题生成的 ID
转小写Getting Startedgetting-started
空格→连字符Hello Worldhello-world
移除标点What's New?whats-new
保留中文安装指南安装指南
保留数字Step 1step-1
连续连字符合并A --- Ba----b
重复 ID 加后缀两个 Hellohello, hello-1

2.3 各平台差异

平台中文处理重复标题特殊字符
GitHub保留加 -1 后缀移除
GitLab保留加 -1 后缀移除
Hugo可配置加 -1 后缀移除
VuePress可配置加 -1 后缀移除
Obsidian保留不重复移除

3. 自定义锚点

3.1 HTML 方式

<a id="custom-anchor"></a>

## 标题

内容...

链接到自定义锚点：

[跳转到自定义位置](#custom-anchor)

3.2 Hugo 短代码

## 标题 {#my-anchor}

内容...

[跳转](#my-anchor)

3.3 Kramdown 方式

## 标题

{: #my-anchor}

[跳转](#my-anchor)

3.4 VuePress 方式

VuePress 自动为标题生成锚点，也支持自定义：

## 标题 <MyAnchor/>

[跳转](#myanchor)

4. 跳转链接语法

4.1 页面内跳转

[跳转到安装](#安装)
[跳转到配置](#配置)
[跳转到 FAQ](#常见问题)

4.2 跨页面跳转

[跳转到其他页面的章节](./other-page.md#章节标题)
[跳转到其他页面](../guide/README.md#概述)

4.3 跨站点跳转

[跳转到外部页面的锚点](https://example.com/docs#section)

5. 实际应用

5.1 README 目录

# My Project

## 目录

- [安装](#安装)
- [配置](#配置)
- [使用](#使用)
  - [基本用法](#基本用法)
  - [高级用法](#高级用法)
- [FAQ](#faq)

## 安装

## 配置

## 使用

### 基本用法

### 高级用法

## FAQ

5.2 交叉引用

在长文档中引用其他章节：

如需了解安装步骤，请参阅[安装指南](#安装指南)。

详细配置选项请参考[高级配置](#高级配置)章节。

5.3 返回顶部

<a id="top"></a>

# 文档标题

... 长文档内容 ...

[↑ 返回顶部](#top)

6. 常见问题

6.1 锚点不生效

问题原因解决方案
点击无反应锚点 ID 不匹配检查大小写和连字符
中文锚点乱码URL 编码问题使用英文锚点或检查编码
重复标题跳转错误多个相同 ID使用自定义锚点区分
跨页面跳转失败路径错误检查相对路径

6.2 调试技巧

// 在浏览器控制台查看所有锚点
document.querySelectorAll('[id]').forEach((el) => {
  console.log(`#${el.id} → ${el.textContent.trim().substring(0, 30)}`);
});

6.3 最佳实践

  • 优先使用英文标题，确保锚点兼容性
  • 避免重复标题，或使用自定义锚点区分
  • 长文档在每章末尾添加返回目录链接
  • 使用自动目录生成工具而非手动维护