How to link to part of the same document in Markdown

Question

I am writing a large Markdown document and would like to place a table of contents of sorts at the beginning that will provide links to various locations in the document  How can I do this  I tried using   a link    MyTitle   where MyTitle is a title within the document but this didn t work

User · Answer

Some additional things to keep in mind if ya ever get fancy with symbols within headings that ya want to navigate to...

# 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

... things like #, ;, &, and : within heading strings are generally are ignored/striped instead of escaped, and one can also use citation style links to make quick use easier.

Notes

GitHub supports the :word: syntax in commits, readme files, etc. see gist(from rxaviers) if using'em is of interest there.

And for just about everywhere else decimal or hexadecimal can be used for modern browsers; the cheat-sheet from w3schools is purdy handy, especially if using CSS ::before or ::after pseudo-elements with symbols is more your style.

Bonus Points?

Just in case someone was wondering how images and other links within a heading is parsed into an 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!"

Caveats

MarkDown rendering differs from place to place, so things like...

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

... on GitHub will have an element with id such as...

id="methodnameoptions--promise"

... where as vanilla sanitation would result in an id of...

id="methodnameoptions-codepromisecode"

... meaning that writing or compiling MarkDown files from templates either requires targeting one way of slugifeing, or adding configurations and scripted logic for the various clever ways that places like to clean the heading's text.

User · Answer

Experimenting  I found a solution using  lt div     gt  but an obvious solution is to place your own anchor point in the page wherever you like  thus   lt a name  quot abcde quot  gt   before and  lt  a gt   after the line you want to  quot link quot  to  Then a markdown link like   link text   abcde   anywhere in the document takes you there  The  lt div     gt  solution inserts a  quot dummy quot  division just to add the id property  and this is potentially disruptive to the page structure  but the  lt a name  quot abcde quot   gt  solution ought to be quite innocuous   PS  It might be OK to put the anchor in the line you wish to link to  as follows      lt a name  quot head1 quot  gt Heading One lt  a gt   but this depends on how Markdown treats this  I note  for example  the Stack Overflow answer formatter is happy with this

User · Answer

Since MultiMarkdown was mentioned as an option in comments   In MultiMarkdown the syntax for an internal link is simple   For any heading in the document simply give the heading name in this format  heading    to create an internal link    Read more here  MultiMarkdown-5 Cross-references      Cross-References      An oft-requested feature was the ability to have Markdown automatically handle within-document links as easily as it handled external links  To this aim  I added the ability to interpret  Some Text    as a cross-link  if a header named    Some Text    exists       As an example   Metadata    will take you to   Metadata  or any of    Metadata      Metadata       Metadata        Metadata         Metadata        Alternatively  you can include an optional label of your choosing to help disambiguate cases where multiple headers have the same title           Overview  MultiMarkdownOverview          This allows you to use  MultiMarkdownOverview  to refer to this section specifically  and not another section named Overview  This works with atx- or settext-style headers       If you have already defined an anchor using the same id that is used by a header  then the defined anchor takes precedence       In addition to headers within the document  you can provide labels for images and tables which can then be used for cross-references as well

User · Answer

Universal solutions  This question seems to have a different answer according to the markdown implementation  In fact  the official Markdown documentation is silent on this topic  In such cases  and if you want a portable solution  you could use HTML   Before any header  or in the same header line  define an ID using some HTML tag  For example   lt a id  Chapter1  gt  lt  a gt  You will see this in your code but not in the rendered document   Full example   See a full example  online and editable  here      Content     Chapter 1   Chapter1     Chapter 2   Chapter2    lt div id  Chapter1  gt  lt  div gt     Chapter 1  Some text here    Some text here  Some text here      Chapter 2  lt span id  Chapter2  gt  lt span gt   Some text here    Some text here  Some text here    To test this example  you must add some extra space between the content list and the first chapter or reduce the window height  Also  do not use spaces in the name of the ids

User · Answer

Using kramdown  it seems like this works well    I want this to link to foo   foo               id  foo       Foo are you    I see it s been mentioned that   foo   foo        Foo   works efficiently  but the former might be a good alternative for elements besides headers or else headers with multiple words

User · Answer

In addition to the above answers   When setting the option number sections  true in the YAML header   number sections  TRUE   RMarkdown will autonumber your sections   To reference those autonumbered sections simply put the following in your R Markdown file    My Section   Where My Section is the name of the section  This seems to work regardless of the section level     My section     My section      My section

User · Answer

yes  markdown does do this but you need to specify the name anchor  lt a name  xyx  gt      a full example     this creates the link  tasks   tasks   later in the document  you create the named anchor  whatever it is called       lt a name  tasks  gt     my tasks  lt  a gt    note that you could also wrap it around the header too    lt a name  tasks  gt      Agile tasks  created by developer   lt  a gt

User · Answer

Gitlab uses GitLab Flavored Markdown  GFM   Here  all Markdown-rendered headers automatically get IDs   One can use mouse to     move mouse over header move mouse over hover selector which becoms visible to the left from header copy and save link using right mouse click  For example in README md file I have header       series expansion formula of the Boettcher function  which gives a link         https   gitlab com adammajewski parameter external angle blob master README md series-expansion-formula-of-the-boettcher-function   Prefix can be removed so the link here is simply   file header   which here means   README md series-expansion-formula-of-the-boettcher-function   Now it can be used as     series expansion formula of the Boettcher function  README md series-expansion-formula-of-the-boettcher-function   One can also do it manually  replace spaces with hyphen sign    Live example is here

User · Answer

This may be out-of-date thread but to create inner document links in markdown in Github use     NOTE  lowercase  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    A good question was made so I have edited my answer  An inner link can be made to any title size using -                  I created a quick example below    https   github com aogilvie markdownLinkTest

User · Answer

Github automatically parses anchor tags out of your headers  So you can do the following   Custom foo description   foo     Foo  In the above case  the Foo header has generated an anchor tag with the name foo Note  just one   for all heading sizes  no space between   and anchor name  anchor tag names must be lowercase  and delimited by dashes if multi-word   click on this link   my-multi-word-header       My Multi Word Header  Update Works out of the box with pandoc too

User · Answer

In pandoc  if you use the option --toc in producing html   a table of contents will be produced with links to the sections  and back to the table of contents from the section headings  It is similar with the other formats pandoc writes  like LaTeX  rtf  rst  etc  So with the command  pandoc --toc happiness txt -o happiness html   this bit of markdown     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    will yield this as the body of the html    lt h1 class  title  gt      True Happiness  lt  h1 gt   lt div id  TOC  gt       lt ul gt           lt li gt               lt a href   introduction  gt Introduction lt  a gt           lt  li gt           lt li gt               lt a href   first-attempts  gt First Attempts lt  a gt           lt  li gt       lt  ul gt   lt  div gt   lt div id  introduction  gt       lt h2 gt           lt a href   TOC  gt Introduction lt  a gt       lt  h2 gt       lt p gt          Many have posed the question of true happiness  In this blog post we propose to solve it       lt  p gt   lt  div gt   lt div id  first-attempts  gt       lt h2 gt           lt a href   TOC  gt First Attempts lt  a gt       lt  h2 gt       lt p gt          The earliest attempts at attaining true happiness of course aimed at pleasure  Soon  though  the downside of pleasure was revealed       lt  p gt   lt  div gt

User · Answer

The pandoc manual explains how to link to your headers  using their identifier  I did not check support of this by other parsers  but it was reported that it does not work on github  The identifier can be specified manually     my heading text   mht   Some normal text here  including a  link to the header   mht    or you can use the auto-generated identifier  in this case  my-heading-text   Both are explained in detail in the pandoc manual  NOTE  This only works when converting to HTML  LaTex  ConTeXt  Textile or AsciiDoc

User · Answer

Some more spins on the  lt a name    gt  trick    lt a id  a-link  gt  lt  a gt  Title ------            lt a id  a-link  gt  lt  a gt  Title  when you wanna control the h N  with   s

User · Answer

There is no such directive in the Markdown spec  Sorry

[markdown] How to link to part of the same document in Markdown?

Bonus Points?

Caveats

Examples related to markdown

Examples related to multimarkdown