dotnet / dotnet/docfx

topicHref for generated metadata only works if the file is in the dest folder

Open
#7,497 0 comments 1 reaction 0 assignees View on GitHub
dotnet toc
Dominant language
C#
Stars
4.4k
Forks
890
Avg merge
2h 9m
Merged PRs (30d)
11

Description

**Operating System**: Windows

**DocFX Version Used**: 2.58

**Template used**: default

````docfx metadata```` generates .yml files including toc.yml to ````dest```` folder. Including this folder in the main ````toc.yml```` adds the generated .yml to the top navigation bar. Using ````topicHref```` to refer to a .md file in the ````dest```` folder is nicely display as the first page for that api, with the toc sidebar on the left. Using ````topicHref```` to refer to a .md file elsewhere it is displayed without the toc sidebar and there is now no way to get to a page that has the toc sidebar.

My problem is this: I don't want any non-generated files in the ````dest```` folder, I want to be able to delete this folder as I please (I will have to run ````docfx metadata```` again), and I want to exclude the generated .yml files from git. Is there a way to do that and still have an intro page to the api?

Contributor guide

Open the contributing guide

Research direction

Reproduce the behavior with DocFX 2.58, the default template, generated metadata in dest, and topicHref pointing to a Markdown file inside and outside dest. Start with the metadata and navigation handling involved in docfx metadata and topicHref. Done means an external intro page can retain the API toc sidebar while dest contains only generated files.

Written by the indexing model from the issue text.

Assessment

Tech stack
markdown
Domain
documentation, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.