Markdown internal links not working in BitBucket README.md

Question

I have a README.md file in a BitBucket project that goes something like

## Table of Contents

* [Document Organization](#document-organization)

...

## Document Organization

When I open up the markdown preview in the browser with Sublime Text the links in the Table of Contents jump to the appropriate sections, but when I upload the file to BitBucket, the URL seems correct but it does not jump to the section.

How can I fix this?

Ionia

Answer 1

I'd check the generated html on the anchor tag, from what I can recall of bitbuckets auto-ids I suspect your link needs to look more like

* [Document Organization](#markdown-header-document-organization)

Crossarm

Multiple headers with the same name get enumerated, e.g. #markdown-header-document-organization_1 , _2, etc – Blanka

Note in the answer that you have to include the prefix markdown-header followed by the section name. Then it works as a bitbucket README.md. Working example: bitbucket.org/tutorials/markdowndemo/overview – Dorcia

Yes, this worked great. Looking at the HTML source from browser helped me understand everything. Basically [Abc Def Xyz] translates into (#markdown-header-abc-def-xyz) automagically. So, just replace blank spaces with hiphen characters and NOTE THAT ALL CHARACTERS GET CONVERTED TO lowercase. So, for example: [SDK API] becomes (#markdown-header-sdk-api) – Pickmeup

Answer 2

Here's a snippet to generate a Table of Contents for Bitbucket readmes (or other markdown files).

cat readme.md  |\
grep "^#" |\
sed 's|^[ ]*||g' |\
awk  -F, '\
BEGIN {
}{
  basic_name=$1;
  anchor=basic_name
  basic_name_no_hash=basic_name
  gsub(/^[#]* /,"",basic_name_no_hash)
  gsub(/[ ]*$/,"",basic_name_no_hash)
  subs_string=basic_name
  subs = gsub(/#/,"",subs_string);
  gsub(/^[#]+ /,"",anchor);
  gsub(/ /,"-",anchor);
  anchor = tolower(anchor);
  {for (i=0;i<subs-1;i++) printf "    " }
  print "* [" basic_name_no_hash "](#markdown-header-" anchor ")";
}
END {
}'

Sophisticate

I haven't tried it yet. But, nice peice of code if it works. Thanks. – Unaccompanied

Answer 3

This may do as well.

According to this: https://confluence.atlassian.com/bitbucket/mark-up-comments-305037452.html, bitbucket supports the Table of Contents extension which can auto-generate links and anchors based on the document headers.

The TOC extension is documented here: https://python-markdown.github.io/extensions/toc/

Add the text "[TOC]" to the beginning of the document for it to be generated.

Wolford

Answer 4

It works for me (Atlassian Bitbucket v6.10.0):

## Table of Contents

* [Document Organization](#document-organization)

...

## Document Organization <a name="document-organization"></a>

Just add an ancor link <a name="document-organization"></a> to the header line.

Maragretmarala

The only working solution I found for BitBucket server. However, it does not work with sections in other files yet? Stuff like [link](filename.md#section) just brings me to the file, but not to the section. – Ariel

Answer 5

Here's a solution that works with BitBucket and other md file editors.

1. [Header one](#custom-id-1)
2. [Header two](#other-id)
    1. [Subheader](#id)
    2. [Subsubheader](#isidtoo)

# Header one <a name="custom-id-1" id="custom-id-1"></a>
# Header two <a name="other-id" id="other-id"></a>
## Subheader <a name="id" id="id"></a>
### Subsubheader  <a name="isidtoo" id="isidtoo"></a>

Conciliator