DocC Markdown format for anchor tags?

I can't seem to find any reference to using anchor tags in markdown that DocC recognizes. Does it exist? I've seen Apple use anchors in the HTML output of some their docs, so I am hoping there is a way to do it.

Hi @pbonneville-nyt!

DocC doesn't have support for anchor tags specifically but does auto-generate anchors for any topic headings (defined as H2 headings). You should be able to reference a given topic section with the following syntax:

<doc:DocumentationPageName#Topic-Heading-Name>

Note that the spaces are replaced with hyphens. Does that help with your use case?

- Ethan

That is the behavior I am looking for, but for higher level H tags (H3, H4) for the scenario that I was asking about.

With your example, it does work like a charm for H2. The content I am trying to link to is nested a little deeper though.

I would actually expect this to work generally for H3/H4 tags. For example:

<!-- MyCatalog.docc/MyArticle.md -->

# My Article

## Overview

Getting started.

### More Details

Further details

A link to <doc:MyArticle#More-Details> should work as expected. Is that not what you're seeing?

I believe there is an issue when trying to link to a specific Topics section. This would be any H3 headings under the ## Topics H2 heading. But that's a special-case, separate from the general use-case of linking to an H3 heading.

- Ethan

So I had it do a link jump once early today with one of my code testing iteration, but now cannot get it to work again, even to an H2 element. I've tried a variety of doc: formats, but can't seem to get it to work at all as the moment.

I have this at the top of my .md Article file:

Overview

<doc:Document-Markdown-Formatting#Add-Code-Listings>

and farther down the page I have this (an H2):

Add Code Listings

The clickable link shows up in the documentation, but does not does jump down to that spot in the article.

Is that the format I should be using?

Given the the undocumented exception you mentioned with the "...H3 headings under the ## Topics H2 heading...", I feel like I should just steer clear of trying to anchor link within the same Article document for the time being since you can't just use doc: links in a documented, straightforward manner.

If the link resolves and produces a clickable link, then you're authoring it correctly and Swift-DocC understands which heading you're linking to.

If the rendered link then isn't working as expected when you click on it, that sounds like a separate bug in the renderer so a bug on bugs.swift.org against the Swift-DocC-Render component would be great so we can track it down.

Topics section are a special-case in DocC because they're automatically generated. This is definitely a bug we'd like to fix but shouldn't affect your general use of anchor links in DocC.

- Ethan