How should I organize a multi-version site?

My Noda Time site hosts the API reference documentation for multiple versions (all past releases, and the current “unstable” code). Each version also has its own user guide, which needs to refer to the API reference.

Obviously these contain the same type and member names by and large, so even though I can easily generate the metadata (yml files) from the source of previous releases easily enough, I can’t use docfx build due to the collisions.

My current plan is to have a separate docfx.json file per release, build the sites as if they were entirely separate, and then stitch them together… but if there’s any better approach, I’d love to hear it.

(I considered post-processing the YML files to add the version number to disambiguate, but that would be awkward in various ways, and lead to ugly URLs.)

[thuannguy]

What is the magic that docs.microsoft.com is using to do versioning? e.g. https://docs.microsoft.com/en-us/aspnet/core/tutorials/first-web-api?view=aspnetcore-3.0&tabs=visual-studio

Is that something that can work out of the box with DocFX or?

[superyyrrzz]

Not soon, but you can track it here: https://github.com/dotnet/docfx/blob/v3/docs/roadmap.md