Search code examples
visual-studio-codemarkdown

Markdown Anchor Link With Same Name But Different Sections

You can link to an anchor heading in markdown quite easily.
[link to anchor heading](#background)

Plenty of stackoverflow questions deal with it such as this one or this one.

But I cannot seem to find a way to link to anchors that share the same name but are in different sections.

So for example, I cannot link to the background section in a different section.
[link to database background](#database#background)

As opposed to say :
[link to front end background](#front-end#background)

This does not work either.
[link to database background](#database##background)

I would expect the markdown anchor link to follow the section path specified. Is this not possible? Or am I using the wrong syntax?

Solution

  • There is no markdown specification that I know of that supports specifying a section-subsection-... format. As I understand it, they're converted to something like <a name=header>header</a> links, and there's no info on what the parent header is.

    A workaround that I use is that when a header name is repeated, it gets a -1 appended to it so you can access with #header-1. The same pattern is applied for the next copy (#header-2), and the next (#header-3) and so forth.

    Here is a sample markdown (working on VS Code 1.38.1):

    # App

[module 1 background](#background)

[module 2 background](#background-1)

[module 3 background](#background-2)

## Module 1

### background

## Module 2

### SubModule 2-1

#### SubSubModule 2-1-1

##### background

## Module 3

### background

    The problem with this workaround is that you'll have to keep track of the order of the duplicate names, which gets quite tedious if you have a lot. The good thing is it's easier to create a link to a duplicate name embedded in a series of headers (#background-1 is easier than ##module2###submodule-2-1####subsubmodule-2-1-1#####background).

    I don't know exactly how or why this is, but VS Code is using the CommonMark specification and the markdown-it library to parse it, as mentioned in Markdown editing doc.