weixin_39614754
weixin_39614754
2020-12-01 13:07

文档站的外部链接支持在后面显示 icon,提示前往外部站点

在 source/文档内容元素/链接.md 的"链接至外部站点“的格式:

markdown 编辑外部链接时,建议使用 [link text](URL 'title text') 格式,这里的 title text 写”前往XXX网站"。正常渲染后,将鼠标悬停在超链接上时,屏幕上会显示 title text。

例如:Markdown 中文技术文档写作风格指南 渲染后显示如下图所示: image

原因:在文档里提供外部链接时,规范作法应该提供一个提示。参考 Handbook of Technical Writing (Gerald J. Alred, writing for the Web 一节)。一个示例是 google developer documentation style guide 里的描述。(https://developers.google.cn/style/cross-references?hl=zh-cn#out-page) image

添加 title 属性原因有三: - 只是这种外链 icon 效果,不一定所有的 writer 都能找到资源或拥有技术能力来完成。这是一个相对简单的办法。 - 按 HTML 语法,写超链接时,提供 title 属性信息,是一种良好的习惯,有益于内容的 accessibility。 - 我的另一个理解:不同网站的使用条款和隐私政策不同,用户使用当前站点,一般默认用户已经接受了当前站点的法律条文。跳出当前站点之前,我们有责任提醒用户当前的链接是去往哪个站点,跳出去之后如果用户发生问题,不是当前站点的责任。

该提问来源于开源项目:yikeke/zh-style-guide

  • 点赞
  • 写回答
  • 关注问题
  • 收藏
  • 复制链接分享
  • 邀请回答

5条回答

  • weixin_39614754 weixin_39614754 5月前

    Hi,我捣鼓了下,坏消息是我用的 readthedocs 主题确实不支持显示 markdown 超链接的悬停文字,这可能跟 sphinx markdown 插件的实现有关。好消息是我配置了下 readthedocs 文档站的 css,目前支持 外链 icon 的效果了: image https://github.com/alphagov/govuk_frontend_toolkit/pull/293

    刚看到的一个关于外部链接 icon 的讨论。可作参考。(不是为了说一定要用或一定不用,就是多个视角)

    点赞 评论 复制链接分享
  • weixin_39686192 weixin_39686192 5月前

    赞,我学习下

    点赞 评论 复制链接分享
  • weixin_39686192 weixin_39686192 5月前

    Hi,我捣鼓了下,坏消息是我用的 readthedocs 主题确实不支持显示 markdown 超链接的悬停文字,这可能跟 sphinx markdown 插件的实现有关。好消息是我配置了下 readthedocs 文档站的 css,目前支持 外链 icon 的效果了: image

    点赞 评论 复制链接分享
  • weixin_39686192 weixin_39686192 5月前

    Sorry 回复有点晚。 是个很好的建议!我测试下 readthedocs 主题是否支持显示悬停文字,Thanks!

    点赞 评论 复制链接分享
  • weixin_39686192 weixin_39686192 5月前

    我测了下,我用的 readthedocs 主题并不支持显示超链接的悬停文字😩,我得捣鼓一下了。我先去我用的主题 repo 那提了个 issue,可以等一下回复~

    点赞 评论 复制链接分享

相关推荐