Как сделать ссылку на часть того же документа в Markdown?


541

Я пишу большой документ Markdown и хотел бы вначале разместить оглавление, которое будет содержать ссылки на различные места в документе. Как я могу это сделать?

Я пытался с помощью

[a link](# MyTitle)

где MyTitleзаголовок в документе, и это не сработало.


1
Ссылка на stackoverflow.com/questions/12204257/… для R Markdown (Rmd).
Этьен Лоу-Декари

1
Единственная проблема, с которой вы столкнулись, заключается в том, что MyTitle должен быть не заголовком, а именем привязки в этом документе (например, <a name="MyTitle"> </a>). Тогда вы сможете использовать исходную ссылку в любом месте документа.
userfuser 25.11.15

7
Принятый ответ не актуален для большинства людей. Вместо этого посмотрите второй ответ: stackoverflow.com/a/16426829/398630
BrainSlugs83

Ответы:


36

В pandoc , если вы используете опцию --tocв создании html, будет создано оглавление со ссылками на разделы и обратно к оглавлению из заголовков разделов. Это похоже на другие форматы, которые пишет pandoc, например LaTeX, RTF, RST и т. Д. Так же и с командой

pandoc --toc happiness.txt -o happiness.html

этот бит уценки:

% True Happiness

Introduction
------------

Many have posed the question of true happiness.  In this blog post we propose to
solve it.

First Attempts
--------------

The earliest attempts at attaining true happiness of course aimed at pleasure. 
Soon, though, the downside of pleasure was revealed.

выдаст это как тело HTML:

<h1 class="title">
    True Happiness
</h1>
<div id="TOC">
    <ul>
        <li>
            <a href="#introduction">Introduction</a>
        </li>
        <li>
            <a href="#first-attempts">First Attempts</a>
        </li>
    </ul>
</div>
<div id="introduction">
    <h2>
        <a href="#TOC">Introduction</a>
    </h2>
    <p>
        Many have posed the question of true happiness. In this blog post we propose to solve it.
    </p>
</div>
<div id="first-attempts">
    <h2>
        <a href="#TOC">First Attempts</a>
    </h2>
    <p>
        The earliest attempts at attaining true happiness of course aimed at pleasure. Soon, though, the downside of pleasure was revealed.
    </p>
</div>

1
Спасибо, это было именно то, что мне было нужно. Я использовал Textmate, чтобы конвертировать Markdown в HTML, переключусь на pandoc.
взаимное исключение

1
Вы можете попробовать демо-пакет Pandoc на Github (есть также emacs pandoc-mode и т. Д.). В tmbundle повторно используется специфичная для MultiMarkdown подсветка синтаксиса, поэтому есть (очень) несколько странностей. Кроме того, многие связанные скрипты сильно настроены - например, Context, а не LaTeX и т. Д. - но идея в том, что пользователи будут изменять их по своему усмотрению, что я нашел довольно простым. Вероятно, он должен быть git clone-ed в самом нижнем или крайнем каталоге tmbundle, ~/Library/Application\ Support/TextMate/Bundlesчтобы упростить интеграцию.
Аппликативное

2
Это добавляет -1к первому повторению идентификатора, -2ко второму и т. Д.
аппликативное

6
Я обнаружил, что мне нужно было добавить параметр --standalone в команду pandoc, чтобы она фактически выводила само содержание в вывод. Без этого переключателя он превратил бы заголовки в ссылки обратно на #toc с именем anchor, но фактически не выводил бы названный anchor и список like.
Дункан Лок

4
Это может ответить на вопрос OP, но для остальных из нас, кто хочет знать, как сделать это в уценке , это довольно бесполезно. - Следующий ответ гораздо полезнее.
BrainSlugs83

937

Github автоматически анализирует теги привязки из ваших заголовков. Таким образом, вы можете сделать следующее:

[Custom foo description](#foo)

# Foo

В приведенном выше случае Fooзаголовок сгенерировал тег привязки с именемfoo

Примечание : только один #для всех размеров заголовков, без пробелов между #и именем привязки, имена тегов привязки должны быть строчными и разделяться черточками, если они состоят из нескольких слов .

[click on this link](#my-multi-word-header)

### My Multi Word Header

Обновить

Работает из коробки pandocтоже.


54
Если ваш заголовок содержит несколько слов «Как этот», замените пробелы дефисами в привязке [just](#like-this-one).
Могсдад

3
Это работает только для заголовков H1? Если ссылка связана с заголовком H2 (т. Е. ## Foo), нужно ли мне также ставить два знака числа в ссылке, т.е. [Foo] (## foo)? Я не могу заставить ваш синтаксис или мой работать (с дополнительным знаком числа).
GrayedFox

7
@GrayedFox, если вы хотите создать ссылку для заголовка ab H2 ## Foo, попробуйте [это моя ссылка на Foo] (# foo) ... то есть: одиночный хеш, без пробела между хешем и строчными буквами-kebab-case-name- of-header
Абдул

4
Совет: проверьте привязку, которая отображается рядом с вашим заголовком на Github, чтобы получить соответствующую ссылку, т. Е. Если она содержит специальные символы, они автоматически удаляются и там отображается правильная ссылка.
Александр Пача

2
Как насчет того, когда заголовки имеют номер? # 3. Третий пункт [Третий пункт] (# 3.-третий.точка) не работает
Адитья

118

Экспериментируя, я нашел решение, использующее, <div…/>но очевидное решение состоит в том, чтобы разместить свою собственную точку привязки на странице, где вы хотите, таким образом:

<a name="abcde">

до и

</a>

после строки, на которую вы хотите «дать ссылку». Тогда ссылка уценки, как:

[link text](#abcde)

В любом месте документа вы попадете туда.

<div…/>Решение вставляет «фиктивный» разделение просто добавить idсобственность, и это потенциально разрушительными для структуры страницы, но <a name="abcde"/>решение должно быть вполне безвредным.

(PS: Возможно, будет правильным поставить якорь в строке, на которую вы хотите сослаться, следующим образом:

## <a name="head1">Heading One</a>

но это зависит от того, как Markdown относится к этому. Замечу, например, что форматировщик ответов Stack Overflow этим доволен!)


2
Если вы сделаете это, вы должны знать, что div лишает другого форматирования уценки, такого как ## headers.
2rs2ts

@ user691859 Можете ли вы уточнить? Возможно, мы можем обновить ответ, чтобы он работал лучше. Я видел, как TextMate подавлял подсветку, пока не отступил в div, но никаких проблем с обработанной уценкой, просматриваемой из браузера.
Стив Пауэлл

В WriteMonkey я обнаружил, что, если мне предшествует любой текст с <div/>несколькими строками ниже, это затрагивает. Вместо этого я должен обернуть текст, на который я ссылаюсь, в полное divпредложение тега, и мне нужно заново УКАЗАТЬ поведение с нуля, используя настоящий HTML. Бу.
2rs2ts

6
Это работает хорошо, спасибо. Для всех, кто интересуется, это также работает с файлами Markdown, размещенными и отображаемыми на GitHub.
Алекс Дин

2
Чтобы быть совместимым с HTML5 , я бы рекомендовал заменить его <a name="head1"/>на <a id="head1"/>.
Бинки

74

Это может быть устаревшая тема, но для создания внутренних ссылок на документы в уценке при использовании Github ...
(ПРИМЕЧАНИЕ: строчные буквы #title)

    # Contents
     - [Specification](#specification) 
     - [Dependencies Title](#dependencies-title) 

    ## Specification
    Example text blah. Example text blah. Example text blah. Example text blah. 
Example text blah. Example text blah. Example text blah. Example text blah. 
Example text blah. Example text blah. Example text blah. Example text blah. 
Example text blah. Example text blah. 

    ## Dependencies Title
    Example text blah. Example text blah. Example text blah. Example text blah. 
Example text blah. Example text blah. Example text blah. Example text blah. 
Example text blah. Example text blah. Example text blah. Example text blah. 
Example text blah. Example text blah. 

Был задан хороший вопрос, поэтому я отредактировал свой ответ;

Внутренняя связь может быть сделано в любом заголовке размера , используя - #, ##, ###, #### я создал быстрый пример ниже ... https://github.com/aogilvie/markdownLinkTest


В вашем примере теги ссылки имеют только один #, а заголовки, на которые они должны ссылаться, имеют два ##; не должны ли они быть одинаковыми?
Карим Бахгат

3
Хороший вопрос. Ответ - нет. (#dependencies-title)знак # in сообщает Github, что это внутренняя ссылка. Текст, который следует, может быть любого размера заголовка. Вот пример теста, который я сделал ... https://github.com/aogilvie/markdownLinkTest
Союзник

1
Это зависит от вкуса уценки? Кажется, что он работает нормально в редакторе уценки, но когда я сохраняю в html или pdf, идентификаторы не добавляются в соответствующие теги. Я был бы в порядке, просто вставив туда якорь, но кажется, что ваш метод намного чище и быстрее.
метеоролог

21

да, уценка делает это, но вам нужно указать имя привязки <a name='xyx'>.

полный пример,

это создает ссылку
[tasks](#tasks)

позже в документе вы создадите именованный якорь (как бы он ни назывался).

<a name="tasks">
   my tasks
</a>

обратите внимание, что вы также можете обернуть его вокруг заголовка.

<a name="tasks">
### Agile tasks (created by developer)
</a>

13

Руководство pandoc объясняет, как связать ваши заголовки, используя их идентификатор. Я не проверял поддержку этого другими парсерами, но сообщалось, что он не работает на github .

Идентификатор можно указать вручную:

## my heading text {#mht}
Some normal text here,
including a [link to the header](#mht).

или вы можете использовать автоматически сгенерированный идентификатор (в этом случае #my-heading-text). Оба подробно объясняются в руководстве Pandoc .

ПРИМЕЧАНИЕ . Это работает только при конвертации в HTML , LaTex , ConTeXt , Textile или AsciiDoc .


9

Некоторые дополнительные вещи, которые следует иметь в виду, если вам когда-либо нравятся символы внутри заголовков, к которым вы хотите перейти ...

# What this is about


------


#### Table of Contents


- [About](#what-this-is-about)

- [&#9889; Sunopsis](#9889-tldr)

- [:gear: Grinders](#it-grinds-my-gears)

- [Attribution]


------


## &#9889; TLDR


Words for those short on time or attention.


___


## It Grinds my :gear:s


Here _`:gear:`_ is not something like &#9881; or &#9965;


___


## &#9956; Attribution


Probably to much time at a keyboard



[Attribution]: #9956-attribution

... вещи , как #, ;, &, и :в товарных строках , как правило , игнорируются / полосатыми вместо спаслись, и можно также использовать Цитирование ссылку стиля , чтобы быстро использовать проще.

Ноты

GitHub поддерживает :word:синтаксис в фиксациях, ReadME файлов и т.д. см сути (от rxaviers) , если using'em представляет интерес есть.

И почти везде можно использовать десятичный или шестнадцатеричный код для современных браузеров; Шпаргалка от w3schools очень удобна , особенно если вы используете CSS ::beforeили псевдоэлементы::after с символами.

Бонусные очки?

На всякий случай, если кому-то интересно, как изображения и другие ссылки внутри заголовка разбираются в id...

- [Imaged](#alt-textbadge__examplehttpsexamplecom-to-somewhere)


## [![Alt Text][badge__example]](https://example.com) To Somewhere


[badge__example]:
  https://img.shields.io/badge/Left-Right-success.svg?labelColor=brown&logo=stackexchange
  "Eeak a mouse!"

Предостережения

Визуализация MarkDown отличается от места к месту, поэтому такие вещи, как ...

## methodName([options]) => <code>Promise</code>

... на GitHub будет элемент с idтаким как ...

id="methodnameoptions--promise"

... где ванильная санитария приведет к id...

id="methodnameoptions-codepromisecode"

... это означает , что писать или компиляцию уценка файлов из шаблонов либо требует ориентации в одну стороны из slugifeing , или добавления конфигураций и скриптовая логики для различных хитроумных способов , что такие места , как очистить текст данной товарной позиции в.


9

Универсальные решения

Этот вопрос, кажется, имеет другой ответ в зависимости от реализации уценки.
На самом деле официальная документация по Markdown ничего не говорит по этой теме.
В таких случаях, и если вы хотите портативное решение, вы можете использовать HTML.

Перед любым заголовком или в той же строке заголовка определите идентификатор с помощью некоторого HTML-тега.
Например: <a id="Chapter1"></a>
вы увидите это в своем коде, но не в отрендеренном документе.

Полный пример:

Смотрите полный пример (онлайн и редактируемый) здесь .

## Content

* [Chapter 1](#Chapter1)
* [Chapter 2](#Chapter2)

<div id="Chapter1"></div>
## Chapter 1

Some text here.  
Some text here.
Some text here.

## Chapter 2 <span id="Chapter2"><span>

Some text here.  
Some text here.
Some text here.

Чтобы проверить этот пример, вы должны добавить дополнительное пространство между списком содержимого и первой главой или уменьшить высоту окна.
Кроме того, не используйте пробелы в названии идентификаторов.


Мм ..., похоже, мило. Попробовал две проблемы: (1). ## Chapter 1нужна открытая линия над ним. (2). Ссылка не работает ...
musicformellons

Ах, это не работает в плагине intellij markdown, который я использовал; но работает в редакторе разметки Macdown.
musicformellons

Все-таки проверено на github: открытая строка над заголовком обязательна, но работает.
musicformellons

@musicformellons, не могли бы вы попробовать без открывающей строки, но правильно закрыть тег span? <br><span id="Chapter1"><span>
ePi272314

да, это работает!
musicformellons

7

В спецификации Markdown такой директивы нет. Сожалею.


Ой! Вы знаете, поддерживает ли MultiMarkdown или Textile это? Я думал о переходе на MD для всей моей документации, но это прерыватель сделки. Спасибо за помощь!
взаимное исключение

5
Что вы подразумеваете под «директивой»? Другие решения именно этой проблемы были размещены здесь.
Зельфир Кальцталь

4

Gitlab использует GitLab Flavored Markdown (GFM)

Здесь "все отображаемые в Markdown заголовки автоматически получают идентификаторы"

Можно использовать мышь, чтобы:

  • наведите курсор мыши на заголовок
  • наведите курсор мыши на селектор наведения, который становится видимым слева от заголовка
  • скопируйте и сохраните ссылку, щелкнув правой кнопкой мыши

    Например, в файле README.md у меня есть заголовок:

## series expansion formula of the Boettcher function

который дает ссылку:

https://gitlab.com/adammajewski/parameter_external_angle/blob/master/README.md#series-expansion-formula-of-the-boettcher-function

Префикс можно удалить, поэтому ссылка здесь просто

file#header

что здесь означает:

README.md#series-expansion-formula-of-the-boettcher-function

Теперь его можно использовать как:

[series expansion formula of the Boettcher function](README.md#series-expansion-formula-of-the-boettcher-function)

Можно также сделать это вручную: заменить пробелы знаком дефиса.

Живой пример здесь


1

С помощью kramdown кажется, что это работает хорошо:

[I want this to link to foo](#foo)
....
....
{: id="foo"}
### Foo are you?

Я вижу, что было упомянуто, что

[foo][#foo]
....
#Foo

работает эффективно, но первый может быть хорошей альтернативой для элементов, кроме заголовков или заголовков с несколькими словами.


1

Так как MultiMarkdown был упомянут как опция в комментариях.

В MultiMarkdown синтаксис для внутренней ссылки прост.

Для любого заголовка в документе просто дайте название заголовка в этом формате, [heading][]чтобы создать внутреннюю ссылку.

Подробнее читайте здесь: MultiMarkdown-5 Перекрестные ссылки .

Перекрестные ссылки

Часто запрашиваемой функцией была возможность автоматической разметки Markdown внутри ссылок на документы так же легко, как и внешних ссылок. С этой целью я добавил возможность интерпретировать [Some Text] [] как перекрестную ссылку, если существует заголовок с именем «Some Text».

Например, [Метаданные] [] приведут вас к # Метаданным (или любым из ## Метаданных, ### Метаданных, #### Метаданных, ##### Метаданных, ###### Метаданных).

Кроме того, вы можете включить необязательную метку по вашему выбору, чтобы помочь устранить неоднозначность в случаях, когда несколько заголовков имеют одинаковый заголовок:

### Обзор [MultiMarkdownOverview] ##

Это позволяет вам использовать [MultiMarkdownOverview], чтобы ссылаться именно на этот раздел, а не на другой раздел под названием Обзор. Это работает с заголовками в стиле atx или settext.

Если вы уже определили привязку, используя тот же идентификатор, который используется заголовком, тогда определенная привязка имеет приоритет.

В дополнение к заголовкам в документе вы можете предоставить метки для изображений и таблиц, которые затем можно будет использовать и для перекрестных ссылок.


0

Еще несколько спинов на <a name="">трюк:

<a id="a-link"></a> Title
------

#### <a id="a-link"></a> Title (when you wanna control the h{N} with #'s)

0

В дополнение к вышеупомянутым ответам,

При настройке параметра number_sections: trueв заголовке YAML:

number_sections: TRUE

RMarkdown будет автоматически пронумеровывать ваши разделы.

Чтобы ссылаться на эти разделы с автопронумерованием, просто добавьте в файл R Markdown следующее:

[My Section]

Где My Sectionназвание раздела

Кажется, это работает независимо от уровня раздела:

# My section

## My section

### My section

Используя наш сайт, вы подтверждаете, что прочитали и поняли нашу Политику в отношении файлов cookie и Политику конфиденциальности.
Licensed under cc by-sa 3.0 with attribution required.