前言

最近项目的文档都托管到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预览工具的展示规则可能不会一致
  • 别人写的博客不一定对
  • 随着工具版本迭代和自己水平的提高，以前自己写的博客也不一定对，所以，工具的版本很重要