【Markdown】使用锚点在页面之间跳转-阿里云开发者社区

开发者社区> 开发与运维> 正文

【Markdown】使用锚点在页面之间跳转

简介: 前言 最近项目的文档都托管到GitLab上的wiki上,包括接口文档。 于是就需要在上一级页面直接通过链接指向下一级详细页面的某个具体API的说明。 所以,需要用到锚点定位。

前言

最近项目的文档都托管到GitLab上的wiki上,包括接口文档。

于是就需要在上一级页面直接通过链接指向下一级详细页面的某个具体API的说明。

所以,需要用到锚点定位。

别人的做法

之前查过别人的博客,大家的做法是

采用div中的id属性,运用HTML中的锚点做法,来做markdown中的锚点

但是经过我的实践,这种做法是不能在GitLab上实现的。

自己动手

环境

线上 -> GitLab中的wiki

本地 ->GitLab托管项目中的wiki项目,本地已经部署了gollum

如何部署gollum本文不做展开,其他人的博客还是靠谱的。

GitLab

举例

第一级页面文件为 menu.md
第二级页面文件为api_list.md
api_list.md中大体布局为如下所示


#h1


##h2/1

text

##h2/2

text

在一级页面直接二级页面某个节点的格式为

[API名字](api_list#h21)

已经明确的规则如下

  • #后面直接接对应的标题内容
  • 不推荐使用中文
  • 如果有/,直接忽略掉
  • 链接不要加.md,如果加上的话,会直接跳转到展示源文件

gollum

经过这次实践,明白了gollum的作用

  • 本地构建wiki页面,方便预览
  • 直接修改文件无效,只渲染git上的最新的提交记录
  • 页面上可以直接修改文件,查看修改效果,但是不会作用在本地文件
  • 页面修改确认无误后,再通过修改页面粘贴到本地文件,防止了为了测试效果反复提交版本

链接跳转规则

[API名字](api_list#h1_h2-1)

和GitLab不同的是

  • 必须从最高一级标题开始,通过_进行连接
  • /-替换

这样就完成了不同页面内跳转的需求。

方法

在预览界面,鼠标停留在需要跳转到到的标题前面,复制链接地址

总结

  • 每个markdown预览工具的展示规则可能不会一致
  • 别人写的博客不一定对
  • 随着工具版本迭代和自己水平的提高,以前自己写的博客也不一定对,所以,工具的版本很重要

版权声明:本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。

分享:
开发与运维
使用钉钉扫一扫加入圈子
+ 订阅

集结各类场景实战经验,助你开发运维畅行无忧

其他文章