README Markdown does not support internal links

Issue #8276 resolved
Joel Fischer
created an issue

For instance:

* [Document Organization](#document-organization)

does not properly link to:

## Document Organization

You can see this issue in the example markdown repository

Comments (45)

  1. Brian Nguyen

    Hi Joel,

    Thanks for letting us know. To get links to headers working you need to add the prefix markdown-header-. i.e. markdown-header-document-organization.

    I've fixed our markdown demo to reflect this.

    Cheers, Brian

  2. Anonymous

    this doesn't work for Atlassian Stash v3.7.0. None of the Table Of Contents links work and it appears to be because the IDs are removed from the header attributes.

  3. Michael Neil

    +1 not being able to link to headers on long READMEs is very frustrating. I'm surprised the parser can't just create an id for headers. This issue needs to be re-opened. I'd commit a patch to make this work if it knew where to or even if I could?

  4. Dmitriy Belik

    I fond solution for myself and it works for other languages. I mark Headers twice. For me in my language and for Bitbucket in English.

    It's looks like this:

    [My header](#markdown-header-any_id)
    #My header #any_id

    My header

    My header #any_id

  5. John Kamenik

    Please reopen.

    A correct approach would be to allow <a name=title></a> so that links #title and somepage#title do not need to know how bitbucket works internally.

    Without this, bitbucket is a useless tool for storing documentation because I cannot both see it rendered on bitbucket and use it as the base for rendered customer documentation.

  6. Nathan Dobrowolski

    Yes, John is right on! This cannot be considered true markdown as long as the consumer must know internal implementation details of bitbucket's parser. The purpose of MarkDown/CommonMark is to be universal! Continuing on the stubborn path of keeping the link generation logic unique just fractures the community.

  7. tgaff

    There's a chance they don't read closed issues and are therefore unaware of the community appeals here. Otherwise I think there'd be some sort of official response here.

    It might make sense to open up another one to try to re-address this.

    Also there are only 31 votes on this; but 51 watchers. Maybe it just needs more votes.

  8. Antanas Sinica

    What's the resolution though? If it's "won't fix" please add justification. Otherwise this issue needs to be fixed. Really annoying when Bitbucket is one of multiple remotes.

  9. Jack Rugile


    Yep, my MD docs are going to be served in multiple locations, and building out special versions with the proper links for each destination just isn't feasible.

  10. Log in to comment