如何在 Markdown 中链接到同一文档的部分内容?
我正在编写一个大型 Markdown 文档,并希望在开头放置一个目录,以提供文档中各个位置的链接。我该怎么做?
我尝试使用:
[a link](# MyTitle)
其中 MyTitle
是文档中的标题,但这不起作用。
如果你对这篇内容有疑问,欢迎到本站社区发帖提问 参与讨论,获取更多帮助,或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱,如果其他用户或者作者回复了您的评论,将不能在第一时间通知您!
发布评论
评论(20)
Github 自动从标头中解析锚标记。因此,您可以执行以下操作:
在上述情况下,
Foo
标头已生成一个名为foo
的锚标记注意:只有一个< code># 对于所有标题大小,
#
和锚点名称之间没有空格,锚点标签名称必须小写,如果是多个单词,则以破折号分隔。更新
也可以与
pandoc
一起使用。Github automatically parses anchor tags out of your headers. So you can do the following:
In the above case, the
Foo
header has generated an anchor tag with the namefoo
Note: just one
#
for all heading sizes, no space between#
and anchor name, anchor tag names must be lowercase, and delimited by dashes if multi-word.Update
Works out of the box with
pandoc
too.这可能是过时的线程,但要在 Github 中的 markdown 中创建内部文档链接,请使用...
(注意:小写#title)
提出了一个很好的问题,所以我编辑了我的答案;
可以使用 -
#
、##
、###
、####< 建立任何标题大小的内部链接/代码>
我在下面创建了一个快速示例......
https://github.com/aogilvie/markdownLinkTest
This may be out-of-date thread but to create inner document links in markdown in Github use...
(NOTE: lowercase #title)
A good question was made so I have edited my answer;
An inner link can be made to any title size using -
#
,##
,###
,####
I created a quick example below...
https://github.com/aogilvie/markdownLinkTest
经过实验,我找到了一个使用
的解决方案,但一个明显的解决方案是将您自己的锚点放置在页面中您喜欢的任何位置,因此:before 和
在您想要“链接”到的行之后。然后,像这样的 Markdown 链接:
文档中的任何位置都会将您带到那里。
解决方案插入一个“虚拟”分区只是为了添加
id
属性,这可能会破坏页面结构,但是
解决方案应该是无害的。(PS:将锚点放在您想要链接到的行中可能没问题,如下所示:
但这取决于 Markdown 如何处理它。例如,我注意到 Stack Overflow 答案格式化程序对此感到满意!)
Experimenting, I found a solution using
<div…/>
but an obvious solution is to place your own anchor point in the page wherever you like, thus:before and
after the line you want to "link" to. Then a markdown link like:
anywhere in the document takes you there.
The
<div…/>
solution inserts a "dummy" division just to add theid
property, and this is potentially disruptive to the page structure, but the<a name="abcde"/>
solution ought to be quite innocuous.(PS: It might be OK to put the anchor in the line you wish to link to, as follows:
but this depends on how Markdown treats this. I note, for example, the Stack Overflow answer formatter is happy with this!)
是的,markdown 确实可以做到这一点,但您需要指定名称锚点
。
一个完整的示例,
这将创建链接
[tasks](#tasks)
在文档的其他位置,您创建命名锚点(无论它被称为什么)。
请注意,您也可以将其包裹在标题周围。
yes, markdown does do this but you need to specify the name anchor
<a name='xyx'>
.a full example,
this creates the link
[tasks](#tasks)
elsewhere in the document, you create the named anchor (whatever it is called).
note that you could also wrap it around the header too.
在 pandoc 中,如果您在生成 html 时使用选项
--toc
,将生成包含各部分链接的目录,并从各部分标题返回到目录。它与 pandoc 编写的其他格式类似,例如 LaTeX、rtf、rst 等。因此,使用命令这一点 markdown:
将生成 html 正文:
In pandoc, if you use the option
--toc
in producing html, a table of contents will be produced with links to the sections, and back to the table of contents from the section headings. It is similar with the other formats pandoc writes, like LaTeX, rtf, rst, etc. So with the commandthis bit of markdown:
will yield this as the body of the html:
只需遵循
[text](#link)
语法并遵循以下准则:-
例如,如果您有以下部分:
您可以使用以下方式添加引用:
asp.net-core
如何变为aspnet-core
,1. python
变为1-python
等。Just follow the
[text](#link)
syntax and follow these guidelines:-
So for example if you have these sections:
You can add a reference by using:
Note how
asp.net-core
becomesaspnet-core
,1. python
becomes1-python
, etc.pandoc 手册解释了如何使用其标识符链接到您的标头。我没有检查其他解析器对此的支持,但据报道它在 github 上不起作用。
可以手动指定标识符:
或者您可以使用自动生成的标识符(在本例中为
#my-heading-text
)。 pandoc 手册中对两者进行了详细解释。注意:此仅在转换为 HTML、LaTex、ConTeXt、<强>纺织或<强>AsciiDoc。
The pandoc manual explains how to link to your headers, using their identifier. I did not check support of this by other parsers, but it was reported that it does not work on github.
The identifier can be specified manually:
or you can use the auto-generated identifier (in this case
#my-heading-text
). Both are explained in detail in the pandoc manual.NOTE: This only works when converting to HTML, LaTex, ConTeXt, Textile or AsciiDoc.
通用解决方案
这个问题似乎根据 markdown 实现有不同的答案。
事实上,Markdown 官方文档对此主题只字不提。
在这种情况下,如果您想要一个可移植的解决方案,您可以使用 HTML。
在任何标头之前或在同一标头行中,使用某些 HTML 标记定义 ID。
例如:
您将在代码中看到这一点,但在渲染的文档中看不到。
完整示例:
此处查看完整示例(在线且可编辑)。
要测试此示例,您必须在内容列表和第一章之间添加一些额外的空间或减小窗口高度。
另外,不要在 ids 名称中使用空格。
Universal solutions
This question seems to have a different answer according to the markdown implementation.
In fact, the official Markdown documentation is silent on this topic.
In such cases, and if you want a portable solution, you could use HTML.
Before any header, or in the same header line, define an ID using some HTML tag.
For example:
<a id="Chapter1"></a>
You will see this in your code but not in the rendered document.
Full example:
See a full example (online and editable) here.
To test this example, you must add some extra space between the content list and the first chapter or reduce the window height.
Also, do not use spaces in the name of the ids.
如果您喜欢想要导航到的标题中的符号,请记住一些其他注意事项...
...诸如
#
、;标题字符串中的
、&
和:
通常会被忽略/删除而不是转义,并且还可以使用引用样式链接使快速使用更容易。奖励积分?
以防万一有人想知道标题中的图像和其他链接如何解析为
id
...注意事项
MarkDown 渲染因地而异,所以像...... .
... GitHub 上将有一个带有
id
的元素,例如...... vanilla 卫生将导致
id
......意味着从模板编写或编译 MarkDown 文件要么需要针对一种slugifeing方式,或者为各种聪明方式添加配置和脚本逻辑喜欢清理标题文本的地方。
Some additional things to keep in mind if ya ever get fancy with symbols within headings that ya want to navigate to...
... things like
#
,;
,&
, and:
within heading strings are generally are ignored/striped instead of escaped, and one can also use citation style links to make quick use easier.Bonus Points?
Just in case someone was wondering how images and other links within a heading is parsed into an
id
...Caveats
MarkDown rendering differs from place to place, so things like...
... on GitHub will have an element with
id
such as...... where as vanilla sanitation would result in an
id
of...... meaning that writing or compiling MarkDown files from templates either requires targeting one way of slugifeing, or adding configurations and scripted logic for the various clever ways that places like to clean the heading's text.
Markdown 规范中没有这样的指令。对不起。
There is no such directive in the Markdown spec. Sorry.
Gitlab 使用 GitLab Flavored Markdown (GFM)
这里“所有 Markdown 渲染的标题都会自动获取 ID”,
可以使用鼠标来:
复制并保存链接使用鼠标右键单击
例如,在 README.md 文件中,我有标题:
## Boettcher 函数的级数展开公式< /code>
给出了一个链接:
前缀可以删除,所以这里的链接很简单,
这意味着:
现在可以用作:
[Boettcher 函数的级数展开公式](README.md#series-expansion-formula-of-the-boettcher-function)
也可以手动完成:用连字符替换空格。
实时示例位于此处
Gitlab uses GitLab Flavored Markdown (GFM)
Here "all Markdown-rendered headers automatically get IDs"
One can use mouse to :
copy and save link using right mouse click
For example in README.md file I have header:
## series expansion formula of the Boettcher function
which gives a link :
Prefix can be removed so the link here is simply
which here means:
Now it can be used as :
[series expansion formula of the Boettcher function](README.md#series-expansion-formula-of-the-boettcher-function)
One can also do it manually: replace spaces with hyphen sign.
Live example is here
它实际上应该有效。我认为你做错的事情是
行不通的,但相反
它也适用于另一个文档的部分
VSCode通过在你写这个时为你提供选项来帮助你
It actually should work. I think the think you are doing wrong is that
won't work, but instead
It also works for sections of another document
VSCode helps you by offering you options when you write this
这对我有用:
这里有 GitHub 预览的更长示例: https://gist.github.com/manero6/ a0a67e8f9ebd7028f6fae51c49208b5d
This works for me:
Longer example with GitHub preview here: https://gist.github.com/manero6/a0a67e8f9ebd7028f6fae51c49208b5d
除了上述答案之外,
在 YAML 标头中设置选项
number_sections: true
时:RMarkdown 将为您的部分自动编号。
要引用这些自动编号的部分,只需将以下内容放入 R Markdown 文件中:
[My Section]
其中
My Section
是部分的名称这似乎与部分无关level:
# 我的部分
## 我的部分
### 我的部分
In addition to the above answers,
When setting the option
number_sections: true
in the YAML header:RMarkdown will autonumber your sections.
To reference those autonumbered sections simply put the following in your R Markdown file:
[My Section]
Where
My Section
is the name of the sectionThis seems to work regardless of the section level:
# My section
## My section
### My section
使用 kramdown,看起来效果很好:
我看到有人提到它
可以有效地工作,但前者可能是除了标题或具有多个单词的标题之外的元素的一个很好的替代方案。
Using kramdown, it seems like this works well:
I see it's been mentioned that
works efficiently, but the former might be a good alternative for elements besides headers or else headers with multiple words.
由于 MultiMarkdown 在评论中被提到作为一个选项。
在 MultiMarkdown 中,内部链接的语法很简单。
对于文档中的任何标题,只需以
[heading][]
格式给出标题名称即可创建内部链接。在此处阅读更多信息:MultiMarkdown-5 交叉引用。
Since MultiMarkdown was mentioned as an option in comments.
In MultiMarkdown the syntax for an internal link is simple.
For any heading in the document simply give the heading name in this format
[heading][]
to create an internal link.Read more here: MultiMarkdown-5 Cross-references.
关于
技巧的更多旋转:
Some more spins on the
<a name="">
trick:就我而言,我正在寻找一个没有 Pandoc 的 TOC 解决方案。每个 TOC 条目都包含一个指向标题的链接,格式为
[显示名称](#-url-formatted-name-of-header)
对于 2 级缩进的简单情况,
结果为:
1.1.最低系统要求
1.2.先决条件
对于包含 3 级或更多缩进级别的一般多级编号列表,该列表无法在 3 级或更高级别进一步缩进(例如
1.3.2.
)。相反,我能找到的最佳解决方案是使用>>>
使用嵌套块引号进行格式化。在 GitHub 上生成精美呈现的目录。如果没有 SO 的 linter 抱怨未格式化的代码,就无法在这里渲染它。
注意1.2.2后面的空白条目。
如果没有空白条目,您的以下行将停留在第三个块引用缩进级别。
与仅使用空格或制表符作为缩进标记“正常工作”的项目符号列表进行对比 -
结果:
目录
以上所有缩进列表都将成功链接到 GitHub markdown 中的以下标头(标头由于某种原因无法在 SO 风格的 markdown 中链接) -
In my case I was looking for a TOC solution without Pandoc. Each TOC entry contains a link to a header in the format
[Display Name](#-url-formatted-name-of-header)
For the simple case of 2 indent levels,
Results in:
1.1. Minimum System Requirements
1.2. Prerequisites
For general multi-level numbered lists containing 3 or more indent levels, the list fails to indent further at levels 3 or higher (such as
1.3.2.
). Instead the best solution I could find is using>>>
to format with nested blockquotes.Results in a nicely rendered TOC on GitHub. Can't render it here without SO's linter complaining about unformatted code.
Note the blank entry after 1.2.2.
Without the blank entry your following lines remain stuck at the 3rd blockquote indent level.
Contrast that with bulleted lists which "just work" using only spaces or tabs as indent markers -
Results in:
Table of Contents
All above indented lists would successfully link to the following headers in GitHub markdown (headers fail to link in SO-flavored markdown for some reason) -
除了前面的答案之外,一些编辑器还支持不同的空格分隔符。例如 Obsidian 使用
%20
(即 URL 编码)作为空格分隔符如上面建议的-
。因此,为了指向 -
您可以将其写为
See doc 了解更多详情
In addition to the previous answers, some editors support different delimiters for spaces. For e.g. Obsidian uses
%20
(i.e. URL Encode) as a delimiter for spaces instead of-
as suggested above.So in order to point to -
you would write it as
See doc for more details
对于降价,这对我有用:
假设您有多个标题,例如
#1。 Helm
,## 1.1 什么是 helm
我发现在 markdown 中使用这些是有效的:第一个是
[Part 1.](#1-helm)
和[Part 1.1](#11-what-is-helm)
,后者自动将普通文本超链接到这些章节。如果使用 VS Code,放置光标并耐心等待,应该会显示一个带有超链接章节的下拉菜单。我认为在执行对其他章节的引用时,应删除空格以及数字之间的.
(如## 1.1 What is helm
中的情况)。For markdowns, this worked for me:
Imagine you have several titles eg
#1. Helm
,## 1.1 What is helm
I found that using these in a markdown works:[Part 1.](#1-helm)
for the first and[Part 1.1](#11-what-is-helm)
for the latter automatically hyperlinked normal text to those chapters. If using VS Code, putting a cursor and with some patience should show a dropdown with the hyperlinked chapters. I think the spaces, and the.
between numbers as in the case of## 1.1 What is helm
is to removed when performing references to other chapters.