Showing results for 
Search instead for 
Did you mean: 
Sign up Log in

Markdown internal links support in Bitbucket Server

smolkin June 7, 2017

Is it possible to use internal links in Markdown files?

None of these ways works in version 4.14:
[Link Title](#markdown-header-testlink)
[Link Title](#testlink)

some text

# Testlink
some text


11 answers

3 accepted

10 votes
Answer accepted
arito melo October 24, 2018

For me it works like this:


The difference between the above and the solution proposed by @Hajaniaina R (web) is that I am omitting the

Pressacco January 15, 2020

Jan 2020: I can confirm that Arito's approach works.

  1. there is no need to include the page name
  2. every in-page link has to include the following prefix: #markdown-header-

Personally, I find it frustrating how Atlassian continues to use it's own proprietary implementations.

  • First there was Markup.
  • Now that BitBucket finally supports MarkDown, they use a magic prefix for for in-page hyperlinks
Like # people like this
Sergio Pedercini April 27, 2020

Personally, I find it frustrating how Atlassian continues to use it's own proprietary implementations.

I agree, it's very frustrating.

Like # people like this
Marko Kirves July 31, 2020

Is there an existing issue on Atlassian Jira for removing the annoying prefix that I could go vote on?

Like # people like this
Anton-V-K August 18, 2020

@Marko Kirves , I wasn't able to find the issue, so I created the one :)

Like # people like this
9 votes
Answer accepted
Jeff Thomas
Atlassian Team
Atlassian Team members are employees working across the company in a wide variety of roles.
June 7, 2017

Hi Pavel,

Yes this is possible. In your Markdown create a link at the top:


and in the body of your document, create the anchor:

<a name="section"></a>


smolkin June 7, 2017

Great! It works. Thanks!

JJ Lin November 28, 2017

This doesn't seem to work in Bitbucket 5.3.2. Is there a different solution for that version?

Joseph Kobti December 8, 2017

if you found any solution please tell me :) 

JJ Lin December 8, 2017

This issue is supposedly fixed in Bitbucket Server 5.3.4 and 5.4.2, but I don't currently have access to either of these versions to verify. See for details.

mxlan September 5, 2018

This works for me on v5.11.1 Bitbucket Server.

Deleted user September 11, 2018

It is not working for me. It is rendering <a name="target"></a> as text and no navigation. I can navigate with other markdown viewers.

Like # people like this
kvernon-maxdigital September 21, 2018

Same as @[deleted] for me

ian_colwell September 24, 2018

I am also experiencing the same issue as @[deleted] describes.

Like Kevin Miller likes this
Ben Kermode September 25, 2018

Same as Rafael

hugo_virgen September 27, 2018

Functionality still broken!!! :/

Like # people like this
okada.shin January 4, 2019

Same as Rafael It just shows a text.

Malcolm Cook September 12, 2019

Jeff (or other Atlassian team member),

Your approach works in my hands.  I would like "id" attribute to also work.  It does now. It should per html spec I think.  Can fix in bitbucket on prem?


I want this to work too:

<a id="section"></a>
Robert Sherman October 2, 2019

This doesn't work. I did as Jeff joy. Apparently a link [return to top](#top) works even though I don't have a link or section header named 'top'. But the other links are dead.

Robert Sherman October 2, 2019

ok so I did eventually get it working, the trick is to commit often and then inspect the id for the header tags and copy/paste--however it seems you can not link to any subheader; that is internal links to #section work, while a hyperlink to ##section-subsection, will not work.

Like Justin Hadella likes this
4 votes
Answer accepted
Hajaniaina R (web) June 7, 2018

We can do something like this

PS: we must add "markdown-header-"  before the id of section

* [Configuration](


# Configuration

mxlan September 5, 2018

This did not work for me, but the above ref using html <a> tag did work:

v5.11.1 bitbucket server.

Helder Magalhães March 3, 2022

This did not work for me, but the above ref using html <a> tag did work

Different scopes:

  • The markdown-header- prefix is used in Bitbucket Cloud (
  • The HTML anchor is used in Bitbucket Server
6 votes
kselyunin February 6, 2019

The `<a>` tag in the header file did not work in my case (Feb. 2019).


What I did let the file rendered as-is and then right-click the corresponding header I wanted to link to, choose inspect from the context menu (I use chrome, choose the similar option in your browser).


You will see generated html similar to the following:

<h1 id="markdown-header-your-awesome-header">...


Use then this ID tag to link to the header from your code like:

[this is my link](#markdown-header-your-awesome-header)


ArnoldYang1 March 15, 2019

This is the one, folks! Nice one, Konstantin.

Troy Weber May 22, 2019

Yea, that works, but that requires manually a edited README (so no typedoc with markdown theme) and frankly it breaks the markdown standard. What a bummer.

Like # people like this
Ana Ludmila August 25, 2021

This was the only one that worked for me. Thank you!

3 votes
Paulius Pupeikis August 19, 2019

In-document links no longer work. Even in this markdown example clicking on any in-document link just reloads the same markdown file but does not jump to the heading.

vitoralbano September 20, 2019

Is there some solution to section links work? 

This feature is really practical for long docs.

Like William Morgan likes this
1 vote
techsturta January 6, 2019

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

0 votes
Javier Leal
I'm New Here
I'm New Here
Those new to the Atlassian Community have posted less than three times. Give them a warm welcome!
January 24, 2024

Use as very good alternative

0 votes
andrew j wright March 16, 2021

I'm seeing anchors being rendered as well.  I had such high hopes of using this wiki product too.

0 votes
rvandenassum January 26, 2021

I'm not sure whether I'm complete mislooking this functionality, but I'm not able to get my wiki work.

Markdown elements are perfectly converted/applied in the Edit > Preview, but NOT in the wiki-url display. 

Some examples:

  • # Heading one
    when showing in preview, this has 'markdown-heading-heading-one' as ID anchor
    when showing in BitBucket wiki no id is generated, but text is wrapped in <h1>
  • [TOC]
    when showing in preview, a complete Table Of Content is generated, with working links
    when showing in Bitbucket wiki '[TOC]' is shown.

So it kind of seems the Bitbucket wiki display uses different libraries to process the markdown to display in the front-end (end-users) vs. what is shown in Preview.

Is this a known issue, or maybe some repository settings I'm missing?

Thanks in advance! 

0 votes
Ilya Alexander S December 14, 2019

it's already 2020 and this still not working.. :|

Like # people like this
0 votes
Wellington Viveiro December 10, 2019

Internal links still not working - using `<a name="foo"></a>` just renders the anchor as text. Any solutions for this?

Suggest an answer

Log in or Sign up to answer
AUG Leaders

Atlassian Community Events