Querverweis (benannter Anker) im Markdown

511

Gibt es eine Markdown- Syntax für das Äquivalent von:

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

... 

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

Antworten:

691 
Take me to [pookie](#pookie)

sollte die richtige Markdown-Syntax sein, um zum Ankerpunkt namens pookie zu springen.

Um einen Ankerpunkt dieses Namens einzufügen, verwenden Sie HTML:

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

Markdown scheint es nichts auszumachen, wo Sie den Ankerpunkt setzen. Ein nützlicher Ort, um es zu setzen, ist in einer Kopfzeile. Zum Beispiel:

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

funktioniert sehr gut. (Ich würde hier demonstrieren, aber der Renderer von SO entfernt den Anker.)

Hinweis zu selbstschließenden Tags und id=Versusname=

In einer früheren Version dieses Beitrags wurde vorgeschlagen <a id='tith' />, die selbstschließende Syntax für XHTML zu verwenden und stattdessen das idAttribut zu verwenden name.

Mit XHTML kann jedes Tag "leer" und "selbstgeschlossen" sein. Das heißt, es <tag />ist <tag></tag>eine Abkürzung für ein übereinstimmendes Paar von Tags mit einem leeren Körper. Die meisten Browser akzeptieren XHTML, einige jedoch nicht. Um browserübergreifende Probleme zu vermeiden, schließen Sie das Tag explizit mit <tag></tag>, wie oben empfohlen.

Schließlich war das Attribut name=in XHTML veraltet, also habe ich es ursprünglich verwendet id=, was jeder erkennt. HTML5 erstellt jetzt jedoch eine globale Variable in JavaScript, wenn es verwendet wird id=, und dies muss nicht unbedingt das sein, was Sie wollen. Daher ist die Verwendung name=jetzt wahrscheinlich freundlicher.

(Vielen Dank an Slipp Douglas , der mir XHTML erklärt hat, und an Nagler , der auf den HTML5-Nebeneffekt hingewiesen hat. Weitere Informationen finden Sie in den Kommentaren und in der Antwort des Naglers. Es name=scheint überall zu funktionieren, obwohl es in XHTML veraltet ist.)

Steve Powell
quelle
1
Sie können nicht sehen, wie Sie eine Verknüpfung zu Ihrer Überschriften-Demo herstellen, nachdem StackOverflow den HTML-Code gerendert hat, da durch das Rendern Ihr <a> -Tag entfernt wird. Das heißt, Sie können nicht in StackOverflow Markdown.
Slipp D. Thompson
2
Dies funktioniert jedoch in anderen, liberaleren Markdown-Renderern, Sie benötigen jedoch ein schließendes <a> -Tag. Das <a> -Tag erlaubt keine Selbstschließung. Außerdem habe ich festgestellt, dass mein Browser den Header überspringt, es sei denn, das <a> -Tag steht vor dem Inhalt des Headers. Korrekturen an Ihren Beispielen.
Slipp D. Thompson
2
Warte, Cowboy. Nur weil Sie kein Styling <a>ohne href haben, heißt das nicht, dass es sich selbst schließt. Sofern ich nicht völlig verrückt bin, rendern beide: test-xhtml11 und [ sln.6bitt.com/public/test-html5.html ( Test- html5) den Rest der Seite innerhalb des <a> -Tags. Prüfen Sie mit einem Webinspektor Ihrer Wahl.
Slipp D. Thompson
4
@ Slipp: OK, ich glaube ich verstehe jetzt. Sie haben codiert <a id="hi"/> rest of doc, aber es wurde wie behandelt <a id="hi"> rest of doc</a>. (Und die Elementanalyse der Seite zeigt dies auch.) Mein Fehler: Ich habe mir die angezeigten Elemente angesehen, nicht die Rohquelle. Denken Sie, dass die Antwort angesichts dieser Beobachtung geändert werden sollte?
Steve Powell
3
Das nameAttribut erstellt auch globale Variablen (siehe stackoverflow.com/questions/3434278/… ), sodass Sie das idAttribut genauso gut wie beabsichtigt als Ziel für Fragment- IDs verwenden können .
Bobby Jack
92

Auf bitbucket.org würde die gewählte Lösung nicht funktionieren. Wenn Sie Header (mit ##) verwenden, können Sie sie stattdessen als Anker referenzieren, indem Sie ihnen den Präfix # markdown-header-my-header-name voranstellen, wobei # markdown-header- ein vom Renderer generiertes implizites Präfix ist Der Rest ist der Titel der unteren Groß- und Kleinschreibung, wobei Bindestriche Leerzeichen ersetzen.

Beispiel

## My paragraph title

erzeugt einen impliziten Anker wie diesen

#markdown-header-my-paragraph-title

Die gesamte URL vor jeder Ankerreferenz ist optional, d. H. 

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

ist äquivalent zu 

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

vorausgesetzt, sie befinden sich auf derselben Seite.

Quelle: https://bitbucket.org/tutorials/markdowndemo/overview (Bearbeiten Sie die Quelle dieser MD-Datei und sehen Sie sich an, wie Anker hergestellt werden).

La Muerte Peluda
quelle
1
Dies kann auch tun. Entsprechend: konfluenz.atlassian.com/bitbucket/… unterstützt Bitbucket die Erweiterung "Inhaltsverzeichnis", mit der Links und Anker basierend auf den Dokumentkopfzeilen automatisch generiert werden können . Die TOC-Erweiterung ist hier dokumentiert: pythonhosted.org/Markdown/extensions/toc.html Fügen Sie den Text "[TOC]" am Anfang des Dokuments hinzu, damit es generiert wird.
Binary Phile
8
In Github ## My paragraph titlewird der folgende Anker erstellt user-content-my-paragraph-title, sodass Sie ihn mit [Text] (# user-content-my -agraph-title) referenzieren können. Ich habe jedoch keine offizielle Dokumentation dafür gefunden.
toto_tico
Das hat mir auch bei Bitbucket geholfen - funktioniert wie ein Zauber.
Scott Byers
1
Dies sind nützliche Informationen. Vielen Dank. Markdown-Renderer ohne die Erweiterungen generieren diese Anker jedoch nicht für Sie, und zusammenstoßende Überschriftennamen führen zu zusammenstoßenden Anker-IDs (oder einem nicht hilfreichen Unterscheidungstrick, wie die Anzahl ausreicht). Explizite Anker-IDs sind besser, kontrollierbarer, unterliegen keinen zufälligen Änderungen aufgrund von Textaktualisierungen (siehe Trick oben) und sind nützlich, um mehr als nur Überschriften zu verankern. Beide Techniken werden im Allgemeinen benötigt.
Steve Powell
Auf stackedit.io [linky](#header) war ein ausreichender Anker und funktionierte auch bei Veröffentlichung in Gist.
Felipe Alvarez
67

Verwenden Sie a name. Die Verwendung von idist in HTML 5 nicht erforderlich und erstellt globale Variablen in Ihrem JavaScript

Siehe HTML 5-Spezifikation, 5.9.8 Navigieren zu einer Fragmentkennung - beide idund namewerden verwendet.

Es ist wichtig zu wissen, dass die meisten Browser IDs immer noch in globale Variablen umwandeln . Hier ist ein kurzer Test . Durch namedie Verwendung von a wird vermieden, dass globale Elemente und daraus resultierende Konflikte erstellt werden.

Beispiel mit einem Namen:

Take me to [pookie](#pookie)

Und der Zielanker:

### <a name="pookie"></a>Some heading
Mikemaccana
quelle
5
Downvoting. Das Argument für globale Variablen ist schwach, da Sie globale Variablen in Ihrem JS ohnehin nicht (direkt) definieren sollten, damit kein Konflikt auftritt. Auch die Semantik von nameund idist unterschiedlich.
Marnen Laibow-Koser
9
@ MarnenLaibow-Koser Niemand diskutiert die Definition globaler Variablen in JS. Wenn Sie eine ID in HTML erstellen, wird in den meisten Browsern ein globales window.someid erstellt.
Mikemaccana
14
@ MarnenLaibow-Koser Viele Bibliotheken (dh nicht Ihre eigene JS, sondern die einer anderen) verwenden einen einzigen globalen - zum Beispiel einen Fineuploader. Wenn Sie ein Element mit der ID fineuploadererstellen, können Sie das fineuploaderModul nicht verwenden . Wenn Sie vermeiden, unnötige globale Elemente zu erstellen, können Sie diese Konflikte vermeiden.
Mikemaccana
5
Es würde mich interessieren, einige Tests dieses Falls durchzuführen und herauszufinden, welcher Vorrang hat. Ich schätze das theoretische Problem, aber in Jahren der clientseitigen Entwicklung hatte ich noch nie eine ID-Unterbrechung eines clientseitigen JS (vorausgesetzt, der HTML-Code war ansonsten gültig). Ich werde sie weiterhin verwenden, wenn sie semantisch angemessen sind, bis ich auf tatsächliche Probleme stoße.
Marnen Laibow-Koser
2
@ MarnenLaibow-Koser Ich (und viele andere) haben HTML-IDs, die echtes JavaScript brechen - es gibt ein sehr praktisches Beispiel in dem Kommentar, auf den Sie antworten! Es gibt viele Styleguides und Firmen, die immer Klassen verwenden, auch für Singletons, und deshalb.
Mikemaccana
17

Markdown-Anker unterstützt die Hash-Marke, sodass ein Link zu einem Anker auf der Seite einfach wäre[Pookie](#pookie)

Das Generieren des Ankers wird in Gruber Markdown nicht unterstützt, sondern in anderen Implementierungen wie Markdown Extra .

In Markdown Extra wird die Anker-ID an eine Kopf- oder Unterüberschrift mit angehängt {#pookie}.

Github Flavored Markdown auf Git-Repository-Seiten (jedoch nicht in Gists) generiert automatisch Anker mit mehreren Markup-Tags in allen Headern (h1, h2, h3 usw.), einschließlich:

  • id="user-content-HEADERTEXT"
  • class="anchor"
  • href="#HEADERTEXT"
  • aria-hidden="true" (Dies ist für ein SVG-Link-Symbol, das beim Mouseover angezeigt wird.)

Ausgenommen das Aria / SVG-Symbol, wenn man schreibt:

  • # Header Title

Github generiert:

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

Daher muss man nichts tun, um die Header-Links zu erstellen, und kann immer mit folgenden Links verknüpft werden:

  • Link zum [Header Title](#header-title)
jeffmcneill
quelle
16

In der ursprünglichen Markdown-Syntax gibt es keine sofort verfügbare Syntax, aber Markdown Extra bietet die Möglichkeit, Headern zumindest IDs zuzuweisen, mit denen Sie dann problemlos verknüpfen können. Beachten Sie auch, dass Sie sowohl in Markdown als auch in Markdown Extra reguläres HTML verwenden können und dass namedas idAttribut in neueren HTML-Versionen durch das Attribut ersetzt wurde .

Du
quelle
9

Für alle, die nach einer Lösung für dieses Problem in GitBook suchen. So habe ich es gemacht (in GitBook). Sie müssen Ihren Header explizit wie folgt kennzeichnen:

# My Anchored Heading {#my-anchor}

Dann verlinke diesen Anker so

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

Eine Lösung und weitere Beispiele finden Sie hier: https://seadude.gitbooks.io/learn-gitbook/

Keyoxy
quelle
Vielen Dank! das funktioniert! das sollte positiv bewertet werden!
Dexter
Beste Antwort! Danke
invis
7

Spät zur Party, aber ich denke, dieser Zusatz könnte für Leute nützlich sein, die mit ihm arbeiten rmarkdown. Es rmarkdowngibt eine integrierte Unterstützung für Verweise auf Kopfzeilen in Ihrem Dokument.

Beliebiger Header definiert durch

# Header

kann durch referenziert werden 

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

Das Folgende ist eine minimale eigenständige .rmdDatei, die dieses Verhalten zeigt. Es kann an .pdfund gestrickt werden .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
quelle
4

Mit dem neuesten Markdown sollten Sie die folgende Syntax verwenden können:

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

Dies sollte den folgenden HTML-Code erstellen:

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

Wenn der Anker Text enthalten soll, fügen Sie einfach den Ankertext in eckige Klammern ein:

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

Ryan McGuinness
quelle
Es scheint, als wüsste nur Marukudiese Syntax. Siehe das Babelmark.
Ulysse BN
3

Für die meisten gängigen Abschriftengeneratoren. Sie haben einen einfachen selbst generierten Anker in jedem Header. Zum Beispiel bei Pandoc ist der generierte Anker ein Kebab-Fall-Slug Ihres Headers.

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

Je nachdem, welchen Markdown-Parser Sie verwenden, kann sich der Anker ändern (nehmen Sie das Beispiel der Antworten von symbolrush und La muerte Peluda, sie sind unterschiedlich!). In diesem Babelmark können Sie generierte Anker sehen, die von Ihrer Markdown-Implementierung abhängen .

Ulysse BN
quelle