Version drop down

[tac0turtle]

Provide a dropdown somewhere on the page for different versions. This dropdown can read from docs/versions

[lovincyrus]

I remember we had a versioning switcher in our early versions of cosmos docs. I'm not sure why that was removed.

cc: @fadeev @nassdonald

[fadeev]

We were not using it, and it wasn't designed, just added in an ad-hoc fashion.

79be201

[nassdonald]

We'd always planned to add it back in, since the architecture of the docs was designed to handle version-switching. It just wasn't a huge priority.

If we were to have a version switcher, do we want to limit the number of versions at all or just show them all? And just to be clear, are these versions of the docs or versions of the SDK? I'm assuming the latter. Never mind, I've just found the original issue for this. 🙂

[clevinson]

I'd love to see this issue prioritized so we can make use of it in the cosmos SDK as well.

We'll definitely be making use of versioning the docs for Cosmos SDK for Stargate, but would be ideal to have this accessible via the UI and be able to set the default to a stable release other than master (which is often pre-release).

[lovincyrus]

The official vuepress does not support versioning (vuejs/vuepress#1018)

tendermint docs
- master
- 0.33
- 0.32

cosmos sdk docs
- master
- 0.38
- 0.37

Related:

• docs: versioned tendermint/tendermint#5241
• 79be201
• docs: deploy multiple versions cosmos-sdk#6308

Different implementation:

1. ava - Create documentation site with vuepress (#1454) avajs/ava#2051
2. lighthouse - Docs versioning mechanism vuejs/vuepress#1018 (comment)
3. pomerium - docs: add versioning to documentation pomerium/pomerium#109
4. docs-devkit - https://github.com/appcelerator/docs-devkit/tree/develop/packages/vuepress/vuepress-plugin-versioning#readme

Next step:

• Versioning #115 (comment)

[lovincyrus]

• after merging Versioning #115, release a new version
• test it on docs-staging branch of cosmos-sdk cosmos/cosmos-sdk@3d09520

Usage

• uses router push to switch version
• user must add an array of versions to themeConfig in .vuepress/config.js in order to use version switcher
• unable to test it locally even after using make build-docs to generate different versions in ~/output locally

homepage

aside bar

mobile

[tac0turtle]

Is this the intended design? It looks different in the above photos

[nassdonald]

No… that doesn't look right. @lovincyrus could this be a cross-browser issue?

appearance: none; might be needed here (with vendor prefixes too) to remove the styling of the native <select>. Also the text should be the version number, e.g. "v0.40" as the screenshots above.

[lovincyrus]

Also the text should be the version number, e.g. "v0.40" as the screenshots above.

I added a select option disabled Version there instead of showing the version number because of how our versioning deployments were set up. The docs theme is unable to utilize vue router to route to different versions due to the version path prefixes (/master, /v0.34) that are being generated with Makefile. Otherwise, it will go https://docs.cosmos.network/master → https://docs.cosmos.network/master/master

In order to make this work, we need to change the version using window.location with each version selection. https://github.com/cosmos/vuepress-theme-cosmos/blob/develop/global-components/TmSelectVersion.vue#L23

That's why we can't show the version text. We're basically refreshing the URL/window history.

[lovincyrus]

@lovincyrus could this be a cross-browser issue?

Most likely. How can I reproduce this?

Update:

• Found it. It's on Firefox.
• Fix version select option appearance #175

[nassdonald]

Okay in that case, if there's no clean workaround to show the version number, let's just change it to "Version" singular. I think that makes more sense, since it's a version selector.

[lovincyrus]

#175

[tac0turtle]

Not sure it's possible but is there a way to make it persistent? Right now if you go from master to any version you lose the capability to go back to a different version.

edit: i see you mention this above

[lovincyrus]

but is there a way to make it persistent?

If you go from /master → /v0.32, you lose the capability to go back to a different version because there is no version switcher in /v0.32. Each version deployment is in its own zone.

We can fix this by adding this to the other versioned docs.

    versions: [
      {
        "label": "v0.32",
        "key": "v0.32"
      },
      {
        "label": "v0.33",
        "key": "v0.33"
      },
      {
        "label": "v0.34",
        "key": "v0.34"
      },
      {
        "label": "master",
        "key": "master"
      }
    ],

[tac0turtle]

Could this also be solved by an optional persistent header? the header is out of scope of the docs, the docs can change but the header stays on all the pages. Not sure how vuepress works and if this is possible?

[tac0turtle]

This isn't solved. Having only updated versions display the dropdown makes it unusable.

I would propose an entire different direction. Instead of building each version separatly we build them together.

We create a script to create folders of versions. This would mean we dont switch branches to build docs but only clone the docs into a specific folder, called versions. Then vuepress builds these docs as a single page. This way the dropdown will persist across versions.

root:

• master
• 0.34
• 0.33
• 0.32

[lovincyrus]

With the setup of gathering versioned docs in a single branch:

1. https://github.com/cosmos/cosmos-sdk/tree/gh-pages
2. https://github.com/CosmWasm/docs/tree/gh-pages

It seems like cosmos/gaia#541 (comment) will solve the persistent issue. 🙏

[tac0turtle]

This won't solve the issue at hand. When you change to a version that doesn't have the dropdown version of the theme it disappears prohibiting you from changing versions any further.

[lovincyrus]

Quick update:

Apparently, the version switcher worked this whole time. But we won't be able to see it with the deployments that use for the docs (AWS CloudFront, Netlify, GitHub Pages). All of them would add a trailing slash at the end of the URLs.

I just deployed the content from this branch https://github.com/CosmWasm/docs/tree/gh-pages to Vercel.

Live site: https://docs.cosmwasm.com
Vercel: https://docs-gh-pages.vercel.app

e.g.

• https://docs-gh-pages.vercel.app/0.13
• https://docs-gh-pages.vercel.app/0.13/

AWS CloudFront, Netlify, GitHub Pages deployments would automatically add a trailing slash at the end of the URL. Vercel doesn’t. Will push a fix asap. #186

[lovincyrus]

When you change to a version that doesn't have the dropdown version of the theme it disappears prohibiting you from changing versions any further.

The version you changed to must have an updated .vuepress/config.js versions.

[tac0turtle]

The version you changed to must have an updated .vuepress/config.js versions.

This is bad UX IMO. what is the problem with:

1. cloning all versions
2. moving the docs folder into a vX folder
3. version dropdown picking which folder to display

This way you avoid needing to update old versions.

Would love to have a call to discuss this.

[tac0turtle]

I have a demo of what I was thinking here: tendermint/tendermint#5932. The only change needed from the theme would be to display what's in the sidebar based off of what version is chosen. Now they all show up, but the version picker displays the correct version when I go to 0.33 or 0.34

[tac0turtle]

had a call with cyrus. We agreed the current approach is the best workaround