Comment créer un lien vers une partie du même document dans Markdown?


541

J'écris un grand document Markdown et je voudrais placer une table des matières de toutes sortes au début qui fournira des liens vers divers emplacements dans le document. Comment puis-je faire ceci?

J'ai essayé d'utiliser

[a link](# MyTitle)

MyTitleest un titre dans le document et cela n'a pas fonctionné.



1
Le seul problème que vous avez rencontré est que MyTitle ne doit pas être un titre, mais le nom d'une ancre dans ce document (comme <a name="MyTitle"> </a>). Ensuite, vous pourrez utiliser votre lien d'origine, n'importe où dans le document.
userfuser

7
La réponse acceptée n'est pas réellement pertinente pour la plupart des gens. Au lieu de cela, voyez la deuxième réponse: stackoverflow.com/a/16426829/398630
BrainSlugs83

Réponses:


36

Dans pandoc , si vous utilisez l'option --tocpour produire du html, une table des matières sera produite avec des liens vers les sections, et de retour à la table des matières à partir des en-têtes de section. Il est similaire avec les autres formats écrits par pandoc, comme LaTeX, rtf, rst, etc. Donc, avec la commande

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

ce peu de démarque:

% 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.

produira ceci comme le corps du 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
Merci, c'était exactement ce dont j'avais besoin. J'utilisais Textmate pour convertir Markdown en HTML, je passerai à pandoc.
recipriversexclusion

1
Vous pouvez essayer la démo Pandoc tmbundle sur Github (il y a aussi le mode pandoc emacs, etc.) La tmbundle réutilise le surligneur de syntaxe spécifique à MultiMarkdown, donc il y a (très) quelques bizarreries. De plus, beaucoup de scripts associés sont hautement personnalisés - par exemple Context, pas LaTeX etc. - mais l'idée est que les utilisateurs les modifient à leur guise, ce que j'ai trouvé assez simple. Il doit probablement être git cloneinséré dans le répertoire tmbundle le plus bas ou le plus externe, ~/Library/Application\ Support/TextMate/Bundlespour simplifier l'intégration.
applicatif

2
Il ajoute -1à la première répétition de l'id, -2à la seconde, etc.
applicatif le

6
J'ai constaté que je devais ajouter l'option --standalone à la commande pandoc pour qu'elle affiche réellement la table des matières elle-même dans la sortie. Sans ce commutateur, cela ferait des en-têtes des liens vers l'ancre nommée #toc, mais ne produirait pas réellement l'ancre nommée et la liste de similaires.
Duncan Lock

4
Cela pourrait répondre à la question du PO, mais pour le reste d'entre nous qui veulent savoir comment le faire en démarque , c'est assez inutile. - La réponse suivante est beaucoup plus utile.
BrainSlugs83

937

Github analyse automatiquement les balises d'ancrage de vos en-têtes. Vous pouvez donc effectuer les opérations suivantes:

[Custom foo description](#foo)

# Foo

Dans le cas ci-dessus, l'en- Footête a généré une balise d'ancrage avec le nomfoo

Remarque : un seul #pour toutes les tailles de titre, pas d'espace entre le #nom de l' ancre, les noms des balises d'ancrage doivent être en minuscules et délimités par des tirets si plusieurs mots .

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

### My Multi Word Header

Mise à jour

Fonctionne aussi avec la boîte pandoc.


54
Si votre en-tête contient plusieurs mots, "Comme celui-ci", remplacez les espaces par des tirets dans l'ancre [just](#like-this-one).
Mogsdad

3
Est-ce que cela ne fonctionne que pour les en-têtes H1? Si je crée un lien vers un en-tête H2 (c.-à-d. ## Foo), dois-je également mettre deux signes numériques dans le lien, c.-à-d. [Foo] (## foo)? Je ne peux pas faire fonctionner votre syntaxe ou la mienne (avec le signe du numéro supplémentaire).
GrayedFox

7
@GrayedFox, si vous voulez créer un lien pour l'en-tête ab H2 ## Foo, essayez [c'est mon lien vers Foo] (# foo) ... c'est-à-dire: hachage unique , pas d'espace entre hachage et minuscule-kebab-case-name- de-tête
Abdull

4
Un conseil: vérifiez l'ancre qui s'affiche à côté de votre en-tête sur Github pour obtenir le lien respectif, c'est-à-dire s'il contient des caractères spéciaux, ils sont automatiquement supprimés et le lien correct y est affiché.
Alexander Pacha

2
Et quand les titres ont un numéro? # 3. Troisième point [Troisième point] (# 3.-troisième.point) ne fonctionne pas
Aditya

118

En expérimentant, j'ai trouvé une solution en utilisant <div…/>mais une solution évidente est de placer votre propre point d'ancrage dans la page où vous le souhaitez, ainsi:

<a name="abcde">

avant et

</a>

après la ligne à laquelle vous souhaitez «lier». Puis un lien de démarque comme:

[link text](#abcde)

n'importe où dans le document vous y emmène.

La <div…/>solution insère une division "factice" juste pour ajouter la idpropriété, ce qui peut potentiellement perturber la structure de la page, mais la <a name="abcde"/>solution devrait être assez inoffensive.

(PS: il peut être correct de placer l'ancre dans la ligne à laquelle vous souhaitez créer un lien, comme suit:

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

mais cela dépend de la façon dont Markdown traite cela. Je note, par exemple, que le formateur de réponses Stack Overflow en est satisfait!)


2
Si vous faites cela, vous devez savoir que le div supprime d'autres formats de démarques, tels que ## headers.
2rs2ts

@ user691859 Pouvez-vous élaborer? Peut-être pouvons-nous mettre à jour une réponse pour qu'elle fonctionne mieux. J'ai vu TextMate supprimer la mise en surbrillance, jusqu'à ce que je fasse un retrait du div, mais aucun problème avec la démarque traitée vue depuis un navigateur.
Steve Powell

Dans WriteMonkey, j'ai trouvé que si je précédais n'importe quel texte, les <div/>plusieurs lignes ci-dessous seraient affectées. Au lieu de cela, je dois encapsuler le texte que je lie dans une divclause de balise complète et je dois RE-SPÉCIFIER le comportement à partir de zéro en utilisant du vrai HTML. Huer.
2rs2ts

6
Cela fonctionne bien, merci. Pour tous ceux qui se demandent, cela fonctionne également avec les fichiers Markdown hébergés et affichés par GitHub.
Alex Dean

2
Pour être compatible avec HTML5 , je voudrais recommander de le remplacer <a name="head1"/>par <a id="head1"/>.
binki

74

Il s'agit peut-être d'un fil obsolète, mais pour créer des liens de document internes dans le démarquage dans Github, utilisez ...
(REMARQUE: #title en minuscules)

    # 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. 

Une bonne question a été posée, j'ai donc modifié ma réponse;

Un lien interne peut être à toutes les tailles de titre à l' aide - #, ##, ###, #### j'ai créé un exemple rapide ci - dessous ... https://github.com/aogilvie/markdownLinkTest


Dans votre exemple, les balises de lien n'ont qu'un seul #, mais les en-têtes qu'elles sont censées lier ont deux ##; ne devraient-ils pas être les mêmes?
Karim Bahgat

3
Bonne question. La réponse est non. le # in (#dependencies-title)indique à Github Markdown qu'il s'agit d'un lien interne. Le texte qui suit peut être de n'importe quelle taille de titre. Voici un exemple de test que j'ai fait ... https://github.com/aogilvie/markdownLinkTest
Ally

1
Cela dépend-il de la saveur du démarque? Il semble que cela fonctionne bien dans l'éditeur de démarques, mais lorsque j'enregistre en html ou pdf, les identifiants ne sont pas ajoutés aux balises appropriées. Je serais bien de jeter une ancre là-dedans, mais il semble que votre méthode soit tellement plus propre et plus rapide.
meteorainer

21

oui, markdown le fait mais vous devez spécifier l'ancre de nom <a name='xyx'>.

un exemple complet,

cela crée le lien
[tasks](#tasks)

plus loin dans le document, vous créez l'ancre nommée (quel que soit son nom).

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

notez que vous pouvez également l'enrouler autour de l'en-tête.

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

13

Le manuel de pandoc explique comment créer un lien vers vos en-têtes, à l'aide de leur identifiant. Je n'ai pas vérifié la prise en charge de cela par d'autres analyseurs, mais il a été signalé que cela ne fonctionne pas sur github .

L'identifiant peut être spécifié manuellement:

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

ou vous pouvez utiliser l'identifiant généré automatiquement (dans ce cas #my-heading-text). Les deux sont expliqués en détail dans le manuel pandoc .

REMARQUE : cela ne fonctionne que lors de la conversion en HTML , LaTex , ConTeXt , Textile ou AsciiDoc .


9

Quelques éléments supplémentaires à garder à l'esprit si jamais vous avez envie de symboles dans les en-têtes vers lesquels vous souhaitez naviguer ...

# 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

... des choses comme #, ;, &et :de la position des chaînes sont généralement sont ignorées / rayées au lieu de échappé, et on peut également utiliser la citation des liens de style pour utiliser rapidement plus facile.

Remarques

GitHub prend en charge la :word:syntaxe dans les commits, les fichiers readme, etc. voir gist (de rxaviers) si les utiliser est intéressant.

Et pour à peu près partout ailleurs, les décimales ou les hexadécimales peuvent être utilisées pour les navigateurs modernes; la feuille de triche de w3schools est très pratique , surtout si l'utilisation de CSS ::beforeou de ::afterpseudo-éléments avec des symboles est plus votre style.

Points bonus?

Juste au cas où quelqu'un se demanderait comment les images et autres liens d'une rubrique sont analysés en 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!"

Avertissements

Le rendu MarkDown diffère d'un endroit à l'autre, donc des choses comme ...

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

... sur GitHub aura un élément avec idcomme ...

id="methodnameoptions--promise"

... où un assainissement à la vanille entraînerait une idde ...

id="methodnameoptions-codepromisecode"

... ce qui signifie que l'écriture ou la compilation de fichiers MarkDown à partir de modèles nécessite soit de cibler une façon de slugifeing , soit d'ajouter des configurations et une logique de script pour les différentes façons intelligentes qui permettent de nettoyer le texte de l'en-tête.


9

Solutions universelles

Cette question semble avoir une réponse différente selon l'implémentation du démarque.
En fait, la documentation officielle de Markdown est muette sur ce sujet.
Dans de tels cas, et si vous souhaitez une solution portable, vous pouvez utiliser HTML.

Avant tout en-tête, ou dans la même ligne d'en-tête, définissez un ID à l'aide d'une balise HTML.
Par exemple: <a id="Chapter1"></a>
vous le verrez dans votre code mais pas dans le document rendu.

Exemple complet:

Voir un exemple complet (en ligne et modifiable) ici .

## 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.

Pour tester cet exemple, vous devez ajouter un espace supplémentaire entre la liste de contenu et le premier chapitre ou réduire la hauteur de la fenêtre.
N'utilisez pas non plus d'espaces dans le nom des identifiants.


Euh ..., semblait sympa. J'ai essayé, deux problèmes: (1). ## Chapter 1a besoin d'une ligne ouverte au-dessus. (2). Le lien ne fonctionne pas ...
musicformellons

Ah, cela ne fonctionne pas dans le plugin de démarquage intellij que j'ai utilisé; mais fonctionne dans l'éditeur de balisage Macdown.
musicformellons

Pourtant, testé sur github: une ligne ouverte au-dessus de l'en-tête est requise, mais cela fonctionne.
musicformellons

@musicformellons pouvez-vous essayer sans ouvrir la ligne mais en fermant correctement la balise span? <br><span id="Chapter1"><span>
ePi272314

oui ça marche!
musicformellons

7

Il n'y a pas une telle directive dans la spécification Markdown. Désolé.


Oh oh! Savez-vous si MultiMarkdown ou Textile le supportent? Je pensais migrer vers MD pour toute ma documentation, mais c'est une rupture de contrat. Merci pour l'aide!
recipriversexclusion

5
Qu'entendez-vous par «directive»? D'autres solutions à exactement le problème ont été publiées ici.
Zelphir Kaltstahl du

4

Gitlab utilise GitLab Flavored Markdown (GFM)

Ici, "tous les en-têtes rendus Markdown obtiennent automatiquement des ID"

On peut utiliser la souris pour:

  • déplacer la souris sur l'en-tête
  • déplacez la souris sur le sélecteur de survol qui devient visible à gauche de l'en-tête
  • copier et enregistrer le lien en utilisant le clic droit de la souris

    Par exemple, dans le fichier README.md, j'ai un en-tête:

## series expansion formula of the Boettcher function

ce qui donne un lien:

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

Le préfixe peut être supprimé, le lien ici est simplement

file#header

ce qui signifie ici:

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

Maintenant, il peut être utilisé comme:

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

On peut aussi le faire manuellement: remplacer les espaces par un trait d'union.

L'exemple en direct est ici


1

En utilisant kramdown, il semble que cela fonctionne bien:

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

Je vois qu'il a été mentionné que

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

fonctionne efficacement, mais le premier pourrait être une bonne alternative pour les éléments autres que les en-têtes ou bien les en-têtes avec plusieurs mots.


1

Depuis MultiMarkdown a été mentionné comme une option dans les commentaires.

Dans MultiMarkdown la syntaxe d'un lien interne est simple.

Pour tout titre du document, donnez simplement le nom du titre dans ce format [heading][] pour créer un lien interne.

Pour en savoir plus, cliquez ici: MultiMarkdown-5 Cross-references .

Références croisées

Une fonctionnalité souvent demandée était la possibilité pour Markdown de gérer automatiquement les liens intra-document aussi facilement que les liens externes. À cet effet, j'ai ajouté la possibilité d'interpréter [Certains textes] [] comme un lien croisé, s'il existe un en-tête nommé «Certains textes».

Par exemple, [Métadonnées] [] vous amènera à # Métadonnées (ou à l'une des ## Métadonnées, ### Métadonnées, #### Métadonnées, ##### Métadonnées, ###### Métadonnées).

Alternativement, vous pouvez inclure une étiquette facultative de votre choix pour aider à lever l'ambiguïté lorsque plusieurs en-têtes ont le même titre:

### Présentation [MultiMarkdownOverview] ##

Cela vous permet d'utiliser [MultiMarkdownOverview] pour faire référence à cette section en particulier, et non à une autre section nommée Overview. Cela fonctionne avec les en-têtes de style atx ou settext.

Si vous avez déjà défini une ancre en utilisant le même identifiant que celui utilisé par un en-tête, alors l'ancre définie est prioritaire.

En plus des en-têtes dans le document, vous pouvez fournir des étiquettes pour les images et les tableaux qui peuvent également être utilisées pour les références croisées.


0

Encore plus de tours sur l' <a name="">astuce:

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

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

0

En plus des réponses ci-dessus,

Lors de la définition de l'option number_sections: truedans l'en-tête YAML:

number_sections: TRUE

RMarkdown numérotera automatiquement vos sections.

Pour référencer ces sections numérotées automatiquement, mettez simplement ce qui suit dans votre fichier R Markdown:

[My Section]

My Sectionest le nom de la section

Cela semble fonctionner quel que soit le niveau de la section:

# My section

## My section

### My section

En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.