Référence croisée (ancre nommée) dans la démarque

513

Existe-t-il une syntaxe de démarque pour l'équivalent de:

Take me to <a href="#pookie">pookie</a>

... 

<a name="pookie">this is pookie</a>
html anchor markdown cross-reference Synesso
la source

Réponses:

692 
Take me to [pookie](#pookie)

devrait être la syntaxe de démarquage correcte pour passer au point d'ancrage nommé pookie.

Pour insérer un point d'ancrage de ce nom, utilisez HTML:

<a name="pookie"></a>

Markdown ne semble pas se soucier de l'endroit où vous placez le point d'ancrage. Un endroit utile pour le mettre est dans un en-tête. Par exemple:

### <a name="tith"></a>This is the Heading

fonctionne très bien. (Je démontrerais ici, mais le moteur de rendu de SO supprime l'ancre.)

Remarque sur les balises à fermeture automatique et id=contrename=

Une version antérieure de cet article suggérait d'utiliser <a id='tith' />, d'utiliser la syntaxe à fermeture automatique pour XHTML et d'utiliser l' idattribut à la place de name.

XHTML permet à n'importe quelle balise d'être «vide» et «auto-fermée». C'est-à-dire, <tag />est une abréviation pour <tag></tag>, une paire de balises appariées avec un corps vide. La plupart des navigateurs acceptent XHTML, mais certains ne le font pas. Pour éviter les problèmes entre navigateurs, fermez la balise explicitement en utilisant <tag></tag>, comme recommandé ci-dessus.

Enfin, l'attribut name=était obsolète en XHTML, donc j'ai utilisé à l'origine id=, ce que tout le monde reconnaît. Cependant, HTML5 crée maintenant une variable globale en JavaScript lors de l'utilisation id=, et ce n'est pas nécessairement ce que vous voulez. Ainsi, l'utilisation name=est désormais susceptible d'être plus conviviale.

(Merci à Slipp Douglas pour expliquer XHTML pour moi, et cloueuse pour pointer le HTML5 effet secondaire - voir les commentaires et cloueuse s » réponse pour plus de détails. name=Semble fonctionner partout, mais il est dépréciée en XHTML.)

Steve Powell
la source
1
Vous ne pouvez pas voir comment créer un lien vers votre démo de titre après que StackOverflow a rendu le code HTML car leur rendu supprime votre balise <a> . Autrement dit, vous ne pouvez pas dans StackOverflow Markdown.
Slipp D. Thompson
2
Cependant, cela fonctionnera dans d'autres moteurs de rendu Markdown plus libéraux, mais vous aurez besoin d'une balise de fermeture <a> ; la balise <a> ne permet pas la fermeture automatique. De plus, j'ai trouvé que mon navigateur passait devant l'en-tête à moins que la balise <a> ne soit avant le contenu de l'en-tête. Corrections apportées à vos exemples.
Slipp D. Thompson
2
Tenez-vous là, cow-boy. Ce n'est pas parce que vous n'avez aucun style sur un <a>sans href qu'il se ferme automatiquement. À moins que je ne sois complètement fou, les deux: test-xhtml11 et [ sln.6bitt.com/public/test-html5.html spell ( test- html5) rendent le reste de la page dans la balise <a>. Allez-y et inspectez avec un inspecteur Web de votre choix.
Slipp D. Thompson,
4
@Slipp: OK je pense que je comprends, maintenant. Vous avez codé <a id="hi"/> rest of doc, mais il a été traité comme <a id="hi"> rest of doc</a>. (Et l'analyse des éléments de la page le montre aussi.) Mon erreur: j'ai regardé les éléments affichés et non la source brute. Pensez-vous que la réponse devrait être modifiée à la lumière de cette observation?
Steve Powell
3
L' nameattribut crée également des variables globales (voir stackoverflow.com/questions/3434278/… ), vous pouvez donc aussi bien utiliser l' idattribut comme cible des URL d'identifiant de fragment, comme prévu.
Bobby Jack
93

Sur bitbucket.org, la solution votée ne fonctionnerait pas. Au lieu de cela, lorsque vous utilisez des en-têtes (avec ##), il est possible de les référencer en tant qu'ancres en les préfixant comme # markdown-header-my-header-name, où # markdown-header- est un préfixe implicite généré par le moteur de rendu, et le reste est le titre d'en-tête en bas de casse avec des tirets remplaçant les espaces.

Exemple

## My paragraph title

produira une ancre implicite comme celle-ci

#markdown-header-my-paragraph-title

L'URL complète avant chaque référence d'ancrage est facultative, c'est-à-dire 

[Some text](#markdown-header-my-paragraph-title)

est équivalent à 

[Some text](https://bitbucket.org/some_project/some_page#markdown-header-my-paragraph-title)

à condition qu'ils soient sur la même page.

Source: https://bitbucket.org/tutorials/markdowndemo/overview (éditez la source de ce fichier .md et regardez comment les ancres sont faites).

La Muerte Peluda
la source
1
Cela peut aussi faire l'affaire. Selon ceci: confluence.atlassian.com/bitbucket/… , bitbucket prend en charge l'extension Table des matières qui peut générer automatiquement des liens et des ancres en fonction des en-têtes de document. L'extension TOC est documentée ici: pythonhosted.org/Markdown/extensions/toc.html Ajoutez le texte "[TOC]" au début du document pour qu'il soit généré.
Binary Phile
8
Dans Github, ## My paragraph titleproduira l'ancre suivante user-content-my-paragraph-title, afin que vous puissiez la référencer avec [du texte] (# user-content-my-paragraph-title). Cependant, je n'ai pas trouvé de documentation officielle pour cela.
toto_tico
Cela m'a également aidé sur Bitbucket - fonctionne comme un charme.
Scott Byers
1
Ce sont des informations utiles; Merci. Cependant, les rendus de démarque sans les extensions ne génèreront pas ces ancres pour vous, et les noms de titre en conflit se traduiront par des ID d'ancrage en conflit (ou une astuce de distinction inutile, comme le nombre suffit). Les identifiants d'ancrage explicites sont meilleurs, plus contrôlables, ne sont pas soumis à des modifications aléatoires en raison des mises à jour de texte (voir astuce ci-dessus) et utiles pour ancrer plus que de simples en-têtes. Les deux techniques sont nécessaires en général.
Steve Powell
Sur stackedit.io [linky](#header) était une ancre suffisante et fonctionnait également lors de sa publication sur Gist.
Felipe Alvarez
67

Utilisez a name. L'utilisation d'un idn'est pas nécessaire en HTML 5 et créera des variables globales dans votre JavaScript

Voir la spécification HTML 5, 5.9.8 Navigation vers un identificateur de fragment - les deux idet namesont utilisés.

Il est important de savoir que la plupart des navigateurs transforment toujours les identifiants en variables globales . Voici un test rapide . L'utilisation d'un nameévite la création de globaux et tout conflit pouvant en résulter.

Exemple utilisant un nom:

Take me to [pookie](#pookie)

Et l'ancre de destination:

### <a name="pookie"></a>Some heading
mikemaccana
la source
5
Downvoting. L'argument de variable globale est faible car vous ne devriez pas définir (directement) de variables globales dans votre JS de toute façon, donc aucun conflit ne se produira. De plus, la sémantique de nameet idest différente.
Marnen Laibow-Koser
9
@ MarnenLaibow-Koser Personne ne discute de la définition de variables globales dans JS. La création d'un ID en HTML crée un window.someid global dans la plupart des navigateurs.
mikemaccana
14
@ MarnenLaibow-Koser De nombreuses bibliothèques (c'est-à-dire pas votre propre JS, mais celle de quelqu'un d'autre) utilisent un seul global - par exemple, fineuploader. Si vous créez un élément avec un ID de fineuploader, vous ne pourrez pas utiliser le fineuploadermodule. Éviter de créer des globaux inutiles permet d'éviter ces conflits.
mikemaccana
5
Je serais intéressé à exécuter quelques tests de ce cas et à savoir lequel a la priorité. J'apprécie le problème théorique, mais au cours des années de développement côté client, je n'ai jamais vu un ID casser un JS côté client (à condition que le HTML soit par ailleurs valide). Je continuerai à les utiliser lorsqu'ils sont sémantiquement appropriés jusqu'à ce que je rencontre des problèmes réels.
Marnen Laibow-Koser
2
@ MarnenLaibow-Koser J'ai (et beaucoup d'autres) eu des identifiants HTML qui brisent le vrai JavaScript - il y a un exemple très pratique dans le commentaire auquel vous répondez! Il existe de nombreux guides de style et entreprises qui utilisent toujours des classes, même pour les singletons, et c'est pourquoi.
mikemaccana
17

Markdown Anchor prend en charge le hachage, donc un lien vers une ancre dans la page serait simplement[Pookie](#pookie)

La génération de l'ancre n'est pas réellement prise en charge dans Gruber Markdown, mais dans d'autres implémentations, telles que Markdown Extra .

Dans Markdown Extra, l'ID d'ancrage est ajouté à un en-tête ou un sous-titre avec {#pookie}.

Github Flavored Markdown dans les pages du référentiel Git (mais pas dans Gists) génère automatiquement des ancres avec plusieurs balises de balisage sur tous les en-têtes (h1, h2, h3, etc.), notamment:

  • id="user-content-HEADERTEXT"
  • class="anchor"
  • href="#HEADERTEXT"
  • aria-hidden="true" (c'est pour une icône de lien svg qui s'affiche au survol de la souris)

Hors icône aria / svg, quand on écrit:

  • # Header Title

Github génère:

  • <h1><a id="user-content-header-title" class="anchor" href="#header-title">Header Title</a></h1>

Par conséquent, il suffit de ne rien faire pour créer les liens d'en-tête et vous pouvez toujours les lier avec:

  • Lien vers le [Header Title](#header-title)
jeffmcneill
la source
16

Il n'y a pas de syntaxe facilement disponible pour le faire dans la syntaxe Markdown d'origine, mais Markdown Extra fournit un moyen d'attribuer au moins des ID aux en-têtes - que vous pouvez ensuite lier facilement. Notez également que vous pouvez utiliser du HTML standard dans Markdown et Markdown Extra, et que l' nameattribut a été remplacé par l' idattribut dans les versions plus récentes de HTML.

Vous
la source
9

Pour tous ceux qui recherchent une solution à ce problème dans GitBook. C'est ainsi que je l'ai fait fonctionner (dans GitBook). Vous devez baliser explicitement votre en-tête, comme ceci:

# My Anchored Heading {#my-anchor}

Puis liez à cette ancre comme ceci

[link to my anchored heading](#my-anchor)

La solution et des exemples supplémentaires peuvent être trouvés ici: https://seadude.gitbooks.io/learn-gitbook/

keyoxy
la source
Merci! cela marche! cela devrait être voté!
Dexter
Meilleure réponse! Merci
invis
7

Tard dans la soirée, mais je pense que cet ajout pourrait être utile pour les personnes qui travaillent avec rmarkdown. Dansrmarkdown y a un support intégré pour les références aux en-têtes dans votre document.

Tout en-tête défini par

# Header

peut être référencé par 

get me back to that [header](#header)

Voici un .rmdfichier autonome minimal qui montre ce comportement. Il peut être tricoté sur .pdfet .html.

---
title: "references in rmarkdown"
output:
  html_document: default
  pdf_document: default
---

# Header

Write some more text. Write some more text. Write some more text. Write some more text. Write some more text. Write some more text. Write some more text. Write some more text. Write some more text. Write some more text. Write some more text. 

Go back to that [header](#header).
symbolrush
la source
4

En utilisant la dernière Markdown, vous devriez pouvoir utiliser la syntaxe suivante:

[](){:name='anchorName'}

Cela devrait créer le code HTML suivant:

<a name="anchorName"></a>

Si vous vouliez que l'ancre ait du texte, ajoutez simplement le texte de l'ancre entre crochets:

[Some Text](){:name='anchorName'}

Ryan McGuinness
la source
Il semble que ne Marukuconnaît que cette syntaxe. Voir le babelmark.
Ulysse BN
3

Pour les générateurs de démarques les plus courants. Vous avez une ancre auto-générée simple dans chaque en-tête. Par exemple avec pandoc , l'ancre générée sera un slug case kebab de votre en-tête.

 echo "# Hello, world\!" | pandoc
 # => <h1 id="hello-world">Hello, world!</h1>

En fonction de l'analyseur Markdown que vous utilisez, l'ancre peut changer (prenez l'exemple des réponses symbolrush et La muerte Peluda, elles sont différentes!). Voir ce babelmark où vous pouvez voir les ancres générées en fonction de votre implémentation de démarque .

Ulysse BN
la source