dead link 检测环节,需要吗?什么时候检测合适?
wangpin34 opened this issue · comments
公司的文档系统摒弃了之前的 rich text cms,换成 github + gatsby,github 用于保存文档内容(markdown 源文件和相关静态资源,目前最主要的是图片),gatsby引擎 + 定制主题生产页面。
文档的内容由 markdown 编写以后,有很多好处,编写效率高,迁移方便(纯文本随便复制黏贴,批量搜索替换)。页面风格灵活可控。但是缺点也是很明显的,不能“所见即所得”,以在编辑时就能根据实际情况调整内容。于是我开发了几款产品来试图解决了这个问题,经过一段时间的探索,最终定型下来的是一款简单的 chrome extension。当用户打开 github 的文件编辑页面,extension 就会被激活,预览框出现在编辑框右边,各占据一半屏幕宽度。用户可以一边编辑,一边预览编辑结果。
随着一段时间的试运行,很多新的需求和问题被收集起来,比如预览文档的宽度问题,mermaid chart 动态渲染问题,侧边栏导航的预览。而最近,一个新的问题进入视线:dead link 检测。什么意思呢?作为技术文档,段落中插入引用链接是非常频繁的。这些链接又分为站内和站外链接。站外链接通常是直接复制三方网站的网页链接,一般不存在 dead link,即网页地址错误(如果未来失效,则是另一种情况,这里不再展开)。而站内链接是由文档编写着根据相关文档的预期路径来填写。为什么不是线上链接呢?因为文档发布的位置根据不同的目的,会有所不同,开发阶段,测试阶段,开放阶段,文档都会存放在不同的路径上,这个链接就不可能是固定的。但是相对的路径是固定的,这个相对的路径,就是目前文档编写者添加站内链接时的使用的链接。
因为是“预期”的路径,所以不可复制线上的。又因为不是线上的地址,所以其有效性不容易辨别,通常的办法,对于我来说,是根据 markdown 文件的路径来判断被索引文档的位置,然后查看该文档是否存在。如果存在,则路径合法,则链接有效。否则,路径非法,链接无效。这就是一个坏链接。
从理论上讲,熟悉文档路径的相对关系之后,只要稍微注意,就能避免站内链接非法的错误,消除 dead link。但是实际中却又是另外一码事,不是每一个文档编写者都对规则了若指掌,存在理解上的似是而非。另一方面,我们得承认犯错是不可避免的,要求文档编写者永远正确是不对的。更好的办法是,提供一种自动化机制,来检测甚至修正错误链接。
好,我们明确了 dead link 检测环节的必要性。那么,怎么检测呢?
首选方案当然是已有的 chrome extension,但是问题在于,文档发布在 github enterprise,比如通过 hpid 登陆后才能查看,所以 chrome extension 的脚本根本没有权限发送 ajax call 来检测网页是否可达。
devops 和 qa 同事建议将检测流程放在 build 阶段,即 gatsby 生产页面的阶段。我们预期的结果是,在 build 的早期,比如加载 markdown 文件的时候,分析文档内容,查找并验证链接。但是这个方案有明显的缺陷,比如必须依赖 build 流程。很多文档编写者直接在 github 上操作,必须在提交后等待 build server 排期,运行,然后从报告中查看结果(如果有错误的话),这是一个很漫长的反馈,效果可想而知。简单来说,这个办法没法解决编辑时的错误,只能事后诸葛亮,那个时候 dead link 已经上线了。
以上的讨论过后,结论是,目前还不具备自行开发 dead link 的条件。我当时给出的解决办法是,chrome extension + 手动检测。当 extension 渲染出链接后,点击链接打开新页面,查看页面是否存在。当时来看,这个办法解决了部分问题。同时,又提供了一个 web app 同样部署在 github enterprise,在这个 app 里编写 markdown,使用第三方的 dead link 检测extension,同样可以迅速的发现 dead link。
但我一直没停止这样的憧憬:提供轻便快捷的办法可以验证站内链接的合法性。当文档编写者在 github 内部编辑链接时,能够及时得到链接是否合法的信息。
有必要再次说明为什么在当前的预览 extension 无法检测 dead link。常规的 dead link 检测办法是这样一个脚本:
fetch(url, {method: 'HEAD'}).then(resp => resp.status === 200 ? 'exists' : 'not found')
既然是 javascript,自然受同源策略保护。在 extension 的域里面访问 github enterprise 自然被阻止。那么,在 content-script.js 里呢?它运行在 github 域。也不行,因为页面实际是部署在 github enterprise 的 pages 下,这也是不同的域。
”可恶的同源策略“。
让我改变思路的是这样一件事情。某天,再又处理了一堆 dead link 后(某几次频繁的文档上线,就会出现这样的问题),我坐下来思考。我们的文档放在 content 目录下,按照 httpd 服务器的策略来处理 request,比如,GET /v1/about,就会返回 content/v1/about.md 回去(当然是加工成 html 的内容)。
github 上 markdown 文件的路径,决定了未来 build 之后文件在网络上被访问时的路径,即链接。
那么,通过链接,反推文档的路径,然后检测这个路径代表的文件是否存在,不就可以证明链接是否合法吗?文件与 content-script.js 在同一个域,dead link 检测脚本畅通无阻。耶!
想通了这个关键,我开始尝试为 extension 添加新的代码,这个时候,我遇到了几个问题。
第一个问题是,因为想要在 content-script.js 使用 package 的内容,于是将其改造为 typescript 代码。因为相关的 babel 配置与 iframe app(预览页面,本质上是一个 create-react-app 生成的 app)冲突,被迫采用 lerna 将项目分成三个 packages。
- shared : message 定义,相关函数
- chrome : content-script.ts
- extension: iframe app
然后因为使用 yarn, 又被迫学习了下 yarn workspace。
还在如何构造 url 上花了一些功夫,走了一点弯路。npm 的 url-join 不支持 relative path,js 原生的 URL ,构造函数里的 base path 竟然对 absolute path 不起作用。折腾了一番,最后 file path 生成方法如下:
const base = `${host}/${owner}/${repo}/blob/${branch}/content`
let filepath: string = link.indexOf('/') === 0 ? urljoin(base, link) : new URL(link, urljoin(base, docPath)).href
base 其实完全可以 hardcode,一时技痒,非得分析结构,然后重新构造,一点 hardcode 都不用,美其名曰以后移植到任何git风格的code base 都无缝使用。
docPath 就是当前文档的路径,对于相对链接,如../../docs
,当然是相对于当前文档的路径。
最后,还有手写的 PromiseAny 和 checkFileExistence:
async function PromiseAny<T>(promises: Array<Promise<T>>) {
const total = promises.length
return new Promise<T>((resolve, reject) => {
let count = 0
let resolved = false
const errors: Error[] = []
promises.forEach((promise, index) => {
promise
.then((d) => {
count++
if (!resolved) {
resolved = true
resolve(d)
}
})
.catch((err) => {
count++
if (!resolved) {
errors[index] = err
if (count >= total) {
reject(errors)
}
}
})
})
})
}
async function checkFileExistence(filepath: string) {
try {
const resp = await fetch(filepath, { method: 'HEAD' })
const status = resp.status
if (status !== 200) {
throw 'File not exists'
}
return true
} catch {
throw `failed to check existence of ${filepath}`
}
}