20

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?

Leo E
  • 709
  • 9
  • 16
  • [The original Markdown](https://daringfireball.net/projects/markdown/syntax) doesn't create header anchors at all. What processor are you using? We'll have to know that if we can help. – ChrisGPT was on strike Sep 14 '19 at 14:01
  • I am generally editing markdown via visual studio code. – Leo E Sep 14 '19 at 14:20
  • I am flexible though if you know of any processor that treats markdown sections the way I suggest. – Leo E Sep 14 '19 at 14:27

4 Answers4

18

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.

Gino Mempin
  • 25,369
  • 29
  • 96
  • 135
  • 1
    Thanks Gino. This indeed works. Unfortunately, it is not sustainable if you edit the document. If you add a background section somewhere in between your first and last mention, you have to edit all the links again. Not sure why they did not do a simple path syntax which is intuitive enough while being sustainable. In the absence of any other viable alternative, I will select yours as the answer. – Leo E Sep 14 '19 at 13:21
9

As stated in the Markdown Guide, some applications allow you to use HTML tags in Markdown-formatted text (e.g. GitHub). Check your Markdown application's documentation to be sure.

If HTML is allowed, you can use the following:

# Front end

- [Background](#front-end-background)

<h2 id="front-end-background">Background</h2>

# Database

- [Background](#database-background)

<h2 id="database-background">Background</h2>

In the example above, <h2> is the same as ##. It also works with other headings.

Rafael Tavares
  • 5,678
  • 4
  • 32
  • 48
0
Sergei-Udris
  • 65
  • 8
0

Just a note - but it doesn't solve the problem here of identical header links that are then re-ordered.

See https://stackoverflow.com/a/70699884/836330 which does make adding header links pretty easy. Identical links show up like this in the Suggestions:

identical markdown header links

But there should be an issue filed to show parent headers in the suggestions (at least as additional info, Ctrl+Space) for identical headers. But there is no automatic reordering of the links or enough info, other than -1, -2, etc. for knowing where those identical headers are located in the files.

Mark
  • 143,421
  • 24
  • 428
  • 436