Anchors to topics sub-sections

[groue]

Feature Name

Anchors to topics sub-sections

Description

The feature is the ability to embed a direct link to a topics sub-section from any web page, with an URL anchor.

For example, given the documentation structure below, this feature enables a direct link to the "My Section" section with the #My-Section anchor:

# Title

## Overview

## Topics

### My Section

- ``someDeclaration()``

For a practical example: the "Querying the Database Schema" section of this DocC page would be addressable with the #Querying-the-Database-Schema anchor.

Currently the link "does not work", i.e. the browser does not scroll down to the section: https://swiftpackageindex.com/groue/grdb.swift/v6.9.0/documentation/grdb/databaseschema#Querying-the-Database-Schema

Motivation

The motivation is that one needs to link to a specific part of the documentation, the one that precisely discusses a given topic.

One may need such a link when writing doc that links to other parts of the doc, but also when answering questions, issues, etc. Both use cases exist in the GRDB library, where there exist GitHub-rendered Markdown documents that link to DocC-generated HTML pages hosted on the Swift Package Index, as well as GitHub issues and discussions where I need to give links to users.

Even better, it would be possible to guarantee the stability of those anchors, even if the title of the section is eventually modified (probably addressed by #345).

Importance

"Inner-linkability" is an important feature, yes.

Alternatives Considered

No response

[groue]

I realize that the feature is available on Apple documentation. Example: https://developer.apple.com/documentation/swift/array#splitting-and-joining-elements

There is even a 🔗 icon next to the title! Oh I'm so jealous 🤤

Is this feature available to all DocC users? cc @finestructure

[finestructure]

Thanks for the ping, @groue ! I’ve noticed some oddities around anchors as well.

I initially thought this wasn’t working but then it started working for one of our own package’s doc when I retested it. I had an issue open at the time: SwiftPackageIndex/SwiftPackageIndex-Server#2091

This here is the doc set: https://swiftpackageindex.com/SwiftPackageIndex/SPIManifest/0.15.0/documentation/spimanifest

Clicking on the “Common Use Cases” links gets you “mostly” to the anchor. I say mostly, because while there’s a scrolling offset to bring the topic in view it isn’t top aligned except for the first one in my testing.

I can’t make sense of why this is working (sort of) in some cases but not in others 🤔

[groue]

Hi @finestructure, I hope you're doing well :-)

Clicking on the “Common Use Cases” links gets you “mostly” to the anchor.

I'm not sure this is the same issue. The "Common Use Cases" is not a ### section below ## Topics (the... topic of this issue):

# Title

## Overview

## Common Use Cases <--

## Topics

### My Section      <--

- ``someDeclaration()``

The "regular" sections are already handled by DocC: you can write <doc:MyDocument#Common-Use-Cases> in DocC-markdown, and the rendered HTML contains an element with id that is the target for the #Common-Use-Cases URL anchor:

<h3 id="Common-Use-Cases">Common Use Cases</h3>

However, sub-topics sections are not handled by DocC (at least, not in Xcode 14.2). And the rendered HTML does not contain any anchored element (at least , not on the SPI-hosted docs):

<h3 data-v-627ab5f4="" class="title">Querying the Database Schema</h3>

[groue]

I say mostly, because while there’s a scrolling offset to bring the topic in view it isn’t top aligned except for the first one in my testing.

I've recently seen a lot of regressions regarding anchors in Safari: scroll never happens, or is delayed (sometimes by several seconds), or the page content has a wrong scroll offset (maybe due to a wrong synchronization between the scroll and the layout of the content above the anchor). I still don't know if those are actual Safari regressions, or badly coded websites that hijack anchor handling. Anchors in GitHub rendered documents, for example, work flawlessly in Chrome (perfect and fast scroll to the expected page region) but are very flaky on Safari 😒

EDIT: how does one removes the navigation sidebar in GitHub? I'm wondering if it isn't the culprit:

[groue]

Anchor icons are there with Xcode 14.3, and on the documentation generated and hosted on http://swiftpackageindex.com.

[groue]

Oh, but the issue was about writing links to sub-sections of the ## Topics section. Reopening.

[natikgadzhi]

When I worked on #632, there's clearly a way to tell the documentation site itself to link to a subheading. So it stands to reason that it knows how to make a link to a subheading.

I wonder if swift-docc-render could have enough information in RenderNode for subheadings to figure out what a link to that subheading would be, and make that "copy" icon like on Apple-native docs?

[davedelong]

I believe I'm hitting this issue as well… I've created a documentation extension for a particular type and used it to arrange the methods and properties into related sections. These get rendered as an <h3 ... id="section-name">, but I can't create a <doc:Type#section-name> link to them.

The docc plugin produces a warning:

Documentation.docc/AnotherPage.md:39:233: warning: 'section-name' doesn't exist at '/MyPackage/Type'