Add version switch support for documents about hinode HOT 15 CLOSED

I released a first alpha to support the basic approach. A live demo is available on https://version-demo.gethinode.com. The codebase can be found on GitHub. The advanced approach is still work in progress, as well as the guide and docs. Feel free to share your feedback!

from hinode.

I did some testing, and noticed the mounting approach introduces some side effects:

• Page links (relrefor ref) might become ambiguous
• Paga aliases might introduce conflicts

Possibly this could be tackled with a shell script. The script would replace all page links with a version-aware shortcode (e.g. docsref and strip all aliases from the mounted files. The mounted files would have to be added to .gitignore.

from hinode.

I released 0.15.0-beta3 to support multi-branch deployments. The demo repository and live demo have been updated too.

Next to some rigorous testing, I plan to work on the following items:

• Add a dismissible alert to the top of the page when a newer version of the docs is available (see Bootstrap PR #38410 for example)
• Update the documentation on https://gethinode.com
• Write a guide on how to enable / configure versioned documentation (basic and advanced)

from hinode.

I have released the final v0.15.0. You can find a guide on https://gethinode.com/guides/versioning/. The guide includes a link to a demo repository.

I'll close the issue for now, feel free to share your feedback anytime.

from hinode.

Glad you like the theme! I'll add your request to the wishlist.

Strategies

Having looked at some of the discussions and examples, supporting versioned documentation is less trivial than it seems. In general, two strategies could be considered:

1. Maintain folders for different versions
2. Maintain separate git branches for different versions

Having looked at some of the discussions and examples, it seems the second approach is the best option. It avoids duplicating content and allows for versioning of the generated site itself too (so for example, the site's layout is also version tracked). This is also the approach used by Bootstrap for example.

The drawback of the second approach is that the deployment becomes a bit more complex. Netlify supports so-called branch deploys, in which you can specify which specific branches to deploy and publish. You would need to redirect specific URL's on the server side to make this work.

Branch deploy: a deploy generated from a branch that is not your production branch. Branch deploys are published to a URL which includes the branch name and two hyphens (--) as a prefix. For example, if a branch is called staging, it will deploy to staging--yoursitename.netlify.app. If you use Netlify DNS, you can enable branch subdomains, so the staging branch example would deploy to staging.yourcustomdomain.com.

Approach

The approach consists of the following steps:

1. Enable branch deploys
   This is mostly a documentation requirement, and is quite specific to the hosting provider.

2. Set server-side redirects
   A file ./layouts/index.redirects would contain the server-side redirects that link a content folder to a server-side URL.

3. Configure version switch
   A version switch would simply navigate to either one of the configured redirects. The available versions should be defined separately, probably in config/default/params.toml.

Examples

Some examples to consider:

• Branch deploys: Dgraph
• Doks versioning

from hinode.

Wow, That's great, thanks for always improving this. 👏 👍

from hinode.

Another strategy that comes to mind is to download the content of a specific release to a temp directory. You can then use hugo mount to add the relevant content to the virtual file system.

Some considerations:

• Avoid duplicating content files (e.g. make use of the repository's tagged releases)
• Avoid hosting-specific deployments (e.g. Netlify branch deployments only work on their platform obviously)
• Ideally the solution is compatible with Linux, macOS, and Windows (although most runners are Linux based, this is not - catering for local development)
• The menu data (data/docs.yml) should be mounted too, and should be version aware
• The approach should work work both locally and as part of a CI/CD workflow

from hinode.

Great, I will give it a try. Thanks

from hinode.

I did some additional experimentation and concluded the mounting approach has too many unwanted side effects. Instead, I intent to support both other two approaches:

1. Basic - Create subfolders within the same repository (e.g. docs/0.9, docs/1.0)
2. Advanced - Support multi-branch deployments (use Git tags to deploy a versioned branch and redirect them on the server)

The idea is to use the site parameters to define the various versions, and to automatically include them in the navbar. I'm working on a test repository at the moment. I'll also prepare a new guide that illustrates the approach. I'll keep you posted.

from hinode.

I'm working on the advanced approach right now. The redirection for Netlify requires some special configuration.

from hinode.

Thanks so much, it is indeed a significant improvement.

from hinode.

Release 0.15.0-beta5 now introduces support for dismissible alerts. The code checks if the current version is the latest and adds an alert to the top of the page if applicable. The alert is version-aware (meaning it checks each individual version page) and can be dismissed per session - open a new tab to clear the session data.

from hinode.

Great work! Then we can close this issue any time.

from hinode.

Thanks! Does it work as expected?

I'll first finish the docs and guide before closing the issue. I'll release the final v0.15.0 next (if any known issues have been addressed).

from hinode.

I'm quite busy recently and will try it later， Thanks again

from hinode.