Add directory-within-build versioning support.

[evankanderson]

Add "directory" versioning scheme, which permits versioned docs in one build. These code changes would resolve #8453 as an intermediate option before the full versioning and translation effort is complete.

If this looks acceptable (given that this is a fairly small patch), I'd be happy to add documentation to docs/setup/setting-up-versioning.md. In the meantime, I've been using a fork and manually copying the built bundle into our assets (knative/docs#6392), which feels kinda gross (I also needed to do this for the search URL, because this needs to override the config JSON data).

Fixes #8453

Usage:

• Set extra.version.provider: directory in mkdocs.yml.
• Place versioned docs in subdirectories named after the version, e.g. /v1.1/, /v1.2/.
• Create a .meta.yml file in each version directory with version metadata, e.g.:

  version: v1.2

• At the top level, create a versions.json file listing available versions, e.g.:

  [
    {"version": "v1.2", title: "v1.2", "alias": "latest"},
    {"version": "v1.1", title: "v1.1"}
  ]

[squidfunk]

Thanks for the PR! I've quickly checked and I would not declare it as a fairly small change. It's a substantial new feature. We're currently in feature freeze and not merging or adding new features ourselves. The reason is that we do not intend to increase the surface of potential changes we need to address with new features added before we release the initial version of our foundational work. I hope that's understandable from a maintainer's point of view.

We can leave this PR open, but I can say with certainty that we'll want to look at versioning holistically, so I'm not sure if we'll merge this PR as it currently stands. I just want to set the right expectations. However, as said, we see the pain with multi-language support and versioning, which is one of the reasons why we started creating a new foundation for Material for MkDocs to finally solve these problems in a way that caters to different versioning / translations schemes.

Long story short: we need a little more time. We're almost there.

[dprotaso]

creating a new foundation for Material for MkDocs

@squidfunk any details on this?

[squidfunk]

@squidfunk any details on this?

@dprotaso yes. Many details on this in the near future. There will be an announcement soon. In the meantime, our blog post on transforming Material for MkDocs explains the motivation for what we've been doing the last 16 months.

[evankanderson]

Thanks for being clear! I also figured that it might be difficult to merge this with whatever is going on in the insiders tree, but thought that the patch might be useful for others in the same boat in the meantime.

Feel free to leave this open but unreviewed for a while if needed.

[evankanderson]

Thanks for the PR! I've quickly checked and I would not declare it as a fairly small change. It's a substantial new feature. We're currently in feature freeze and not merging or adding new features ourselves. The reason is that we do not intend to increase the surface of potential changes we need to address with new features added before we release the initial version of our foundational work. I hope that's understandable from a maintainer's point of view.

I completely understand! I carefully said "fairly small patch" rather than "change", because introducing additional versioning providers is definitely a new API surface that I can understand wading into carefully.

If you'd like feedback or early testing of changes, I'd be willing to take a look in a couple weeks. (I have some other irons in the fire before then that I've been neglecting.) Feel free to reach out to me here, on CNCF Slack (@Evan Anderson), or at [email protected].