Quick hacky version dropdown

[DMRobertson]

Very rough prototype. Corners cut everywhere. Bad javascript habits. I learned babby's first web development back when the <font> tag was cool.

Closes #951. (Sort of. We'd need to regenerate /v1.1 and /v1.2 to include the switcher.

• In conf.toml, define a list of historical version strings.
• Use these to generate a select element in the navbar.
  • Mark the current version of the spec as the selected option.
  • Include a noscript fallback without the selector.
• Add a piece of Javascript which does the following onDOMContentLoaded:
  • Look at the URL for a path segment of the form /v1.1/ or /latest/.
  • If we can't find this, remove the dropdown and replace it with the fallback content.
  • Add an event listener so that selecting a different version changes the version-specific path segment in the URL. No attempt is made to ensure that the new URL exists.
    • The "historical" section is special cased. Selecting it navigates you to the current spec's changelog page which explains about the r0.x.y versions.

Somewhat cribbed from what docs.python.org does, but written from scratch. (And much less robust.) The machinery for that lives here, but I haven't dug too hard into their setup.

Preview: https://pr1131--matrix-spec-previews.netlify.app

[DMRobertson]

I emulated the spec.matrix.org deployment as follows:

git branch -D dmr/v1.2
git checkout -b dmr/v1.2 v1.2
git cherry-pick dmr/version-switcher
# resolve merge and complete the cherry-pick

git branch -D dmr/v1.1
git checkout -b dmr/v1.1 v1.1
git cherry-pick dmr/version-switcher
# resolve merge and complete the cherry-pick

git switch dmr/version-switcher
hugo --baseURL /unstable -d spec/unstable
git switch dmr/v1.2
hugo --baseURL /v1.2 -d spec/v1.2
hugo --baseURL /latest -d spec/latest
git switch dmr/v1.1
hugo --baseURL /v1.1 -d spec/v1.1

python -m http.server --directory spec

[DMRobertson]

Will leave this parked for now, but can come back to it if there's interest.

[richvdh]

I'm interested. Can you give it a newsfragment so that the CI runs and we can see what it looks like?

[DMRobertson]

I'm interested. Can you give it a newsfragment so that the CI runs and we can see what it looks like?

Part of the trouble is that Netlify only builds one version of the spec, rather than all the versions (/v1.1/, /v1.2/, /latest/, /unstable/) hosted on spec.matrix.org

[DMRobertson]

Here's a demo I recorded locally. Unfortunately OBS studio wasn't capturing the dropdown menu that pops up, but it's hopefully convincing enough.

demo.mp4

[turt2live]

that video looks good enough imo, and the code is good enough too. What are the concerns keeping this in draft?

[DMRobertson]

What are the concerns keeping this in draft?

Nothing as such, other than it being a big hack. It could use some hands-on testing from others too.

I'm not sure how the spec gets deployed (i.e. is this feasible? It's not just a case of "merge and it's done"). This would need a new version of v1.1 and v1.2 (and now v1.3) to be built which includes the selector.

[turt2live]

We can try to build v1.1, v1.2, and v1.3 again though if it ends up not working out then ohwell.jpg - we already don't have links for r0.5.0 (for example).

[richvdh]

Correct me if I'm wrong, but does this mean that old spec versions will not include newer spec versions on the dropdown, unless we rebuild all previous spec versions on each release? That doesn't sound entirely tenable.

Can we populate the list of of versions from a separate https://spec.matrix.org/versions.json or something?

[DMRobertson]

does this mean that old spec versions will not include newer spec versions on the dropdown, unless we rebuild all previous spec versions on each release?

That's correct. FWIW I think that's what Python's docs seem to do, at least when I had a quick look at it last.

[richvdh]

ok, I don't think rebuilding all past versions of the spec on each release is something we particularly want to do.

Can you make the javascript populate the dropdown from a json file at /versions.json or something?