在 Markdown 中包含参考链接作为 GitHub 上的项目符号列表

问题描述 投票:0回答:4

目前我正在 GitHub 上一个项目的 README.md 文件中使用此 Markdown 文本:

See the docs of [testthat][3] on how to write unit tests.

Links
-----

- http://www.rstudio.com/products/rpackages/devtools/
- https://github.com/hadley/testthat
- http://r-pkgs.had.co.nz/tests.html

---

[1]: http://www.rstudio.com/products/rpackages/devtools/
[2]: https://github.com/hadley/testthat
[3]: http://r-pkgs.had.co.nz/tests.html

我不喜欢这种重复,但我不知道我有什么选择。如果我删除显式的项目符号列表,那么 GitHub 将不会显示参考链接。如果我删除参考链接,那么 GitHub 会显示项目符号列表(当然),但上面的“testthat”等嵌入式链接不起作用。

还有比复制更好的方法吗?我错过了什么?

github markdown
4个回答
26
投票

受到@mb21的启发,我想这将是正确的方法

See the docs of [testthat][2] on how to write unit tests.

Links
-----

- [RStudio Devtools][1]
- [testthat][2]
- [More unit test examples][3]

[1]: https://stackoverflow.com/users/214446/mb21
[2]: https://github.com/hadley/testthat
[3]: http://r-pkgs.had.co.nz/tests.html

也就是说,逐字包含链接且没有有意义的标题并不是一个好习惯。我应该仅将链接 URL 保留在底部的参考链接部分,并在项目符号列表中使用有意义的标题。

当您在 GitHub 上查看此内容时,URL 应该并不重要,如果您确实想知道,可以将鼠标移到上面。当您以纯文本形式查看此内容时,现在链接具有有意义的标题,这是有关 URL 的有用的附加信息。


15
投票

我会写如下:

See the docs of [testthat][1] on how to write unit tests.

Links
-----

- [RStudio Devtools](http://www.rstudio.com/products/rpackages/devtools/)
- [Testthat](https://github.com/hadley/testthat)
- [Tests][1]

[1]: http://r-pkgs.had.co.nz/tests.html

这回答了你的问题吗?如果没有的话,你就得澄清一下。


4
投票

8年后的答案!

您的问题的答案将取决于您的 Markdown 解析器支持什么。如今,大多数解析器都支持 CommonMark(加上一些调味)。但是,不要认为这是理所当然的并仔细检查它。如果不支持 CommonMark,请尝试使用“vanilla”Markdown 语法,如下所述。请注意,“普通”Markdown 规范存在缺陷,可能会导致链接损坏(几乎是设计使然)。

使用 CommonMark

如果你能保证你的Markdown解析器支持CommonMark,那么你可以用简单的方式做到这一点:

Writing unit tests is explained in the [Unit Testing] website

[Unit Testing]: https://unittesting.somedomain.com

在 CommonMark 规范(当前版本 0.30)的 Links 部分中,您会看到“链接”由 链接文本链接目标标题 组成,每个链接都有自己的语法和怪癖。例如,如果链接目标包含空格,则需要将其括在

<angled brackets>
中,或者如果链接文本是某种代码,则允许编写

[`AwesomeClass`](<../docs/awesome class.md>]

注意

this部分我使用CommonMark语法,因此您可以单击 “编辑”按钮可查看我用于“真实”示例的语法。

使用普通 Markdown

普通的 Markdown 规范只需要一组额外的尖括号,中间没有任何内容,如 links 部分所述。

Writing unit tests is explained in the [Unit Testing][] website

[Unit Testing]: https://unittesting.somedomain.com

注意

this部分我只使用了普通的Markdown语法。 Stack Overflow 的 Markdown 解析器支持 CommonMark 和 vanilla Markdown。这并非偶然,因为 CommonMark 旨在与原始规范兼容(尽可能!)。 Stack Overflow 确实声明他们在 Markdown 帮助页面中使用 CommonMark 规范。

Tl;博士

See the docs of [`testthat`] on how to write unit tests.

Links
-----

- [RT Studio dev tools]
- [`testthat`]
- [R Packages]

---

[RT Studio dev tools]: http://www.rstudio.com/products/rpackages/devtools/
[`testthat`]: https://github.com/hadley/testthat
[R Packages]: http://r-pkgs.had.co.nz/tests.html

0
投票

试试这个:

### Main Text

  

In the world of programming, Python is a very popular language[^1]. It has a simple and readable syntax which makes it accessible for beginners[^2]. Many developers use it for various applications like web development, data analysis, and artificial intelligence[^3].

### Footnotes

  

[^1]: Python was created by Guido van Rossum and first released in 1991.  
[^2]: Its syntax emphasizes code readability and uses indentation to define code blocks.  
[^3]: For web development, frameworks like Django and Flask are commonly used; for data analysis, libraries such as Pandas and NumPy are popular; and in artificial intelligence, TensorFlow and PyTorch are often employed with Python.

  

When this Markdown text is rendered in a compatible viewer or editor (like some Markdown preview features in text editors or on platforms that support Markdown), the footnotes will usually be shown in an appropriate way, often at the bottom of the page or in a separate section dedicated to footnotes.
© www.soinside.com 2019 - 2024. All rights reserved.