Add directory-within-build versioning support. #8454
Conversation
…e build.
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.:
```yaml
version: v1.2
```
* At the top level, create a `versions.json` file listing available versions, e.g.:
```json
[
{"version": "v1.2", title: "v1.2", "alias": "latest"},
{"version": "v1.1", title: "v1.1"}
]
```
Signed-off-by: Evan Anderson <[email protected]>
|
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. |
@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. |
|
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. |
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 ( |
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 theconfigJSON data).Fixes #8453
Usage:
extra.version.provider: directoryinmkdocs.yml./v1.1/,/v1.2/..meta.ymlfile in each version directory with version metadata, e.g.:versions.jsonfile listing available versions, e.g.:[ {"version": "v1.2", title: "v1.2", "alias": "latest"}, {"version": "v1.1", title: "v1.1"} ]