dotnet / dotnet/docfx

[Feature Request] Symbol when an article has a different primary TOC

Open
#11,131 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
C#
Stars
4.4k
Forks
890
Avg merge
2h 11m
Merged PRs (30d)
10

Description

**Is your feature request related to a problem? Please describe.**

When the same article is listed in two or more `TOC.yml` files (tables of contents), DocFX chooses one of those as the primary TOC that will be displayed when a user views that article. This can result in a jarring change when the user is browsing articles in one TOC and ends up seeing another TOC without having expected that to happen.

**Describe the solution you'd like**

In the table of contents, show 🔗 or another symbol next to the name of the TOC item, to warn the user that the current TOC is not primary for that article and selecting the article will cause a different TOC to be displayed.

**Describe alternatives you've considered**

I can edit the `TOC.yml` files and append 🔗 symbols to the `name` properties of TOC items, but:

* It is easy to forget to do this to a TOC item. An automatic build-time solution would be more reliable.
* That causes the symbol to be underlined as part of the hyperlink on hover, and I'd rather keep the symbol outside the hyperlink. (If it were injected using HTML `class` and CSS `::after`, that would make it easy to customize.)
* The symbol also appears in the "Next" and "Previous" links that the "modern" template generates below neighbouring articles. I'm not sure whether that is good or bad.
* There might be a risk of those symbols ending up in the breadcrumb bar too, although perhaps that can't happen.

**Additional context**

The choice of primary TOC can currently be controlled via the `order` property, which is documented in .

Contributor guide

Open the contributing guide

Research direction

Start by tracing how TOC.yml entries are processed and rendered in the modern template, paying attention to primary-TOC selection and the generated Next and Previous links. The change is complete when non-primary TOC entries display a customizable symbol outside the article hyperlink without incorrectly affecting breadcrumbs or other navigation.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp
Domain
documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.