Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add a new guideline about adding external link hint #8

Merged
merged 3 commits into from
Oct 16, 2020

Conversation

yikeke
Copy link
Owner

@yikeke yikeke commented Oct 15, 2020

请简要描述你改动的内容(有的话也请提供参考的 issue 或其他链接)

To close #6

  1. 在链接一节加了相应的 guideline
  2. 根据此 guideline 修改了一些链接

以下建议来自 oldLady344 ,Thanks a lot!


在 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 yikeke added the New feature New feature or request label Oct 15, 2020
@@ -37,3 +37,9 @@ Markdown 链接中方括号 () 里的内容即为该链接的路径。链接的
- 链接路径应尽量统一风格。例如,链接至非外部站点时应统一使用相对路径或绝对路径,不建议混用相对路径和绝对路径。

- 建议减少将用户链至外部站点的次数,以免外部站点的页面失效而影响用户体验。

Copy link
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi,你想帮忙 review 下这一段 guideline 吗?@oldLady344

Copy link
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

我先合了,上线看看效果,如果有问题可以再提 PR,谢谢~

@yikeke yikeke merged commit 5b4f137 into master Oct 16, 2020
@yikeke yikeke deleted the add-external-link-hint branch October 16, 2020 06:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
New feature New feature or request
Projects
None yet
Development

Successfully merging this pull request may close these issues.

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