How to create a local xrefmap.yml in an hierarchy
- Dominant language
- C#
- Stars
- 4.4k
- Forks
- 890
- Avg merge
- 2h 11m
- Merged PRs (30d)
- 10
Description
**Describe the problem**
I want to have a hierarchy of documentation using cross references. I expected that the TOC file would have been picked up where a specific document has an uid, but it didn't. I've also tried using a separate xrefmap.yml, and it worked, but I get DocFx build warnings.
Hierarchy:
- docs
- doc/platform
- docs/services
- docs/reference
I don't want relative references between md-files in these various folder-hierarchies (e.g. not from services to platform). This is only allowed using xref: links.
I don't want to include a YAML header in the document, as the content is also used in Azure DevOps WIKI pages.
I have created a document in docs/platform/adr with the name 123456-something.md.
I have added the UID "123456-something" for this file to the TOC.
RESULT: it's ignored by DocFx.
Next, I have created an xrefmap.yml manually in docs/platform like this:
```yaml
### YamlMime:XRefMap
sorted: true
references:
- uid: 123456-something
name: Something
href: /docs/platform/adr/123456-something.html
```
I have referenced the file in docfx.json:
```json
"xref": [
"docs/platform/xrefmap.yml"
]
```
When I run DocFx to build the docs, I get this warning (which I currently ignore):
> Warning:[BuildCommand.BuildCore.Build Document.Load]Unable to handle following files: docs/platform/xrefmap.yml. Do they miss `YamlMime` as the first line of file, e.g.: `### YamlMime:ManagedReference`?
If I change the header to YamlMime:ManagedReference no warning is given, but the process just crashes:
> Error:Microsoft.DocAsCode.Build.Engine.Incrementals.BuildCacheException: Full build hasn't loaded model
> docs/platform/xrefmap.yml
> at Microsoft.DocAsCode.Build.Engine.HostService.<>c__DisplayClass100_1.b__1()
> at Microsoft.DocAsCode.Build.Engine.Incrementals.IncrementalUtility.RetryIO(Action action)
> at System.Threading.Tasks.Parallel.<>c__DisplayClass42_0`2.b__1()
> at System.Threading.Tasks.Task.InnerInvokeWithArg(Task childTask)
> at System.Threading.Tasks.Task.<>c__DisplayClass176_0.b__0(Object )
**Context (please complete the following information):**
- DocFx version: 2.59.4.0
- OS: Windows
Contributor guide
Assessment
This issue has not been assessed yet.