Left Nav and Breadcrumbs behaviour when using Reference TOCs (modern template, DocFx 2.75.3)

[lanthonyneville]

I don't know if this is by design or a bug ... for me it is an issue, but maybe there is a reason it works like this, so can anyone shed light?

The issue: if a TOC.yml contains references to sub-folder contents via Reference TOCs, then the behaviour of the Left Nav and Breadcrumbs is as follows:

• Left Nav: the scope of the nav links is limited to the links in the sub-folder's TOC.yml (previously all links from the root were present)
• Breadcrumbs: the sub-folder name is left out of the breadcrumbs for all pages under the sub-folder

Example:

The TOC.yml in the root of my site contains 2 links (this defines the top nav bar ... these are Reference TOCs as per the recommendation but these are not the links with the issue I am talking about (read on ...):

- name: Standard Products
  href: StandardProducts/
- name: Internal Systems
  href: InternalSystems/

The TOC.yml in the InternalSystems sub-folder contains 2 links (this defines the left nav when under Internal Systems); the 1st uses a Nested TOC and the 2nd uses a Reference TOC:

- name: Intranet
  href: Intranet/TOC.yml
- name: Gemini
  href: Gemini/

If I click on Intranet in the left nav, the left nav expands to show the links in Intranet/TOC.yml (preserving the parent and sibling links). When navigating to any of these, the left nav is preserved and the breadbrumbs show the full path to the current page, e.g.: Internal Systems > Intranet > Development > DocFx

However, if I click on Gemini in the left nav, I navigate to the 1st navigable page under Gemini, and the left nav only shows the the links in Gemini/TOC.yml (I would prefer it to preserve the the parent and sibling links). At this point the Breadcrumbs shows only Internal Systems (I would expect it to show Internal Systems > Gemini). Then, if I navigate to any pages in sub-folders below Gemini, breadbrumbs omit Gemini from the path to the current page, e.g.: Internal Systems > Deployment > Custom Applications (this is an issue because the use now has lost the context for where they are).

[lanthonyneville]

If noone has any comment on this, I will log it as a bug as the behaviour for this case (using Reference TOCs) seems inconsistent with the other cases (Nested TOCs and direct links to .md files).

[filzrev]

The TOC.yml in the InternalSystems sub-folder contains 2 links (this defines the left nav when under Internal Systems); the 1st uses a Nested TOC and the 2nd uses a Reference TOC:

Is there any reason it can't use Nested TOC for both elemens?

As far as tested on my environment.
docfx behavior is consistent between versions (tested on 2.59.4, 2.65.0, 2.76.0) and between templates (default/modern)
So it seems to be by design.

[lanthonyneville]

@filzrev it would be useful to have both options, because the different behaviours suit different use cases. Using a Reference TOC (i.e. a link like this: href: Gemini/) is useful for the top menu or a left nav link where you want to navigate straight to the default page within a subfolder. Using a Nested TOC (i.e. a link like this: Intranet/TOC.yml) is useful for left nav links where you want to drill down through an expanding menu before selecting the link you want to navigate to.

When I said the behaviour was inconsistent, I didn't mean it had changed in a recent version. I meant that with a Nested TOC you loose the context of where you are in the overall site navigation (because the parent disappears from the nav, and also the breadcrumbs) whereas with a Reference TOC it is preserved.

If the behaviour of Nested TOC nav links has always been this way, I wonder if it is because they were primarily used in the top nav where by definition there is no parent, so no-one noticed the odd behaviour until they started to be used in the left nav.

[filzrev]

Using Nested TOC for both elements is suggested as temporary workaround.

I agree with your opinion. that current docfx behaviors of Reference TOC is confusing when it's used on non-root TOCs.
And it's reasonable to creating Featue Request issue.

---

As far as I knows.
Currently docfx render TOC with following steps.

1. Conceptual markdown document is associated to single TOC file.
2. Associated TOC path(toc.html) is embedded to <meta name="docfx:tocrel" tag on generated HTML.
3. TOC is rendered by toc.ts by using docfx:tocrel data when navigated to page.

And docfx:tocrel is set as following .

1. When using Nested TOC syntax.

• Child document's docfx:tocrel is set to merged parent TOC file path. (e.g./InternalSystems/toc.html)

2. When using Reference TOC syntax.

• Child document's docfx:tocrel is set to child TOC file. (e.g. /InternalSystems/Gemini/toc.html)