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

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

[a link](# MyTitle)

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

В 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>

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

[Custom foo description](#foo)

# Foo

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

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

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

### My Multi Word Header

Обновить

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

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

<a name="abcde">

до и

</a>

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

[link text](#abcde)

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

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

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

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

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

Это может быть устаревшая тема, но для создания внутренних ссылок на документы в уценке при использовании 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

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

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

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

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

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

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

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

Руководство 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 .

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

# What this is about


------


#### Table of Contents


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

- [⚡ Sunopsis](#9889-tldr)

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

- [Attribution]


------


## ⚡ TLDR


Words for those short on time or attention.


___


## It Grinds my :gear:s


Here _`:gear:`_ is not something like ⚙ or ⛭


___


## ⛤ 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 , или добавления конфигураций и скриптовая логики для различных хитроумных способов , что такие места , как очистить текст данной товарной позиции в.

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

Этот вопрос, кажется, имеет другой ответ в зависимости от реализации уценки.
На самом деле официальная документация по 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.

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

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

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)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

number_sections: TRUE

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

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

[My Section]

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

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

# My section

## My section

### My section