dotnet / dotnet/docfx

Linking from one version to another

Open
#4,346 1 comment 2 reactions 0 assignees View on GitHub
versioning xref
Dominant language
C#
Stars
4.4k
Forks
890
Avg merge
2h 9m
Merged PRs (30d)
11

Description

(Feature request, so most bug template fields aren't particularly relevant.)

For Noda Time documentation, we use the version support within the build config of docfx (see [file](https://github.com/nodatime/nodatime.org/blob/master/build/docfx/docfx-unstable.json)) to build multiple versions of the API documentation at once.

We've recently separated out the serialization documentation into a separate "version". This works fine in most ways, but the serialization package refers to the main package, and it would be nice to link appropriately when the serialization documentation refers to a main package type (e.g. in parameters). I'd need to specify which version to link to, of course, but that's easy enough to choose.

I've currently managed to work around this by adding:

```json
"xref": [
"https://nodatime.org/2.4.x.xrefmap.yml"
],
```

to the *root* of the `build` element, expecting that it doesn't affect any of the "main package" builds, which will be self-contained in terms of references - I'm assuming that a local reference is preferred over one from a xref file. (That appears to be the case at the moment.) It still doesn't feel ideal though.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.