Documentation site: versioning

I am currently making a documentation site. I would like to have subfolder in URL for different versions:

  • mysite.com/0.7/get_started
  • mysite.com/0.6/get_started

I can think of two solutions:

  1. maintain folders for different version containing duplicate or similar contents
  2. maintain separate git branches for different versions

I would like to pursue the second way, but do not know where to start. Any ideas or alternative suggestions?


Found a real-life example but do not know how it is solving this problem:

for me is the first choice the best

/current/get_started
/0.6/get_started

The first path can linked and is always up to date.

Thanks for your work.

Looking at that site, if you switch between versions, it is not only the content that changes, but also the layout.

So I guess what they do is to version the rendered site, and that makes sense for several reasons.

So, a (scripted would be better) workflow for a new release could be:

  1. hugo --destination static/CURRENT_VERSION
  2. Add CURRENT_VERSION to Site.Params.versions or something
  3. Start working on NEXT_VERSION

@bep I think you mentioned this elsewhere, but perhaps we should do something similar with the. Ew docs site? I could certainly use your scripting expertise in this area when/if we get to that point. Thanks!

I don’t think I said that; what I did say one time was: “It is better to finish one thing before you start another task.”

And we will not add any versioning history of the docs site until we reach 1.1.

2 Likes

@sungwoncho I wish I could be of more assistance, but instead I’ll ask for a favor: when you do get this up and running, I’d certainly appreciate you sharing your successes with the forums because I’d like to try something like this with future versions of the docs site. Thanks!

As a cool FYI, It’s nice to know that our current search provider allows for version-based search when we eventually get there. @sungwoncho I don’t know if your current project is open source, but I thought this might be good search solution for you as well if you’re in the market for such a thing :smile:

Example:

http://cordova.apache.org/docs/en/latest/

From the Algolia forums:

2 Likes

Hey, I am solving same thing now. I started with your first solution, but I can’t find out how to make menu which will be different in each version depending on version content directory structure… How did you solve this problem ??

Hi @sungwoncho, so were you able to figure this out ? I did look at the cordova example posted by @rdwatters , but I am not sure what other config goes with it , and its not visible or not entirely hugo based. If someone has a working example for this, I would love to learn more.
Thanks

Hey, I have figured this out. Here is the code: https://github.com/dgraph-io/dgraph/tree/master/wiki

It has been a while since we implemented the solution, and I no longer work for that project. Having said that, if I recall correctly, the main idea is to build for different branches and serve results via nginx. Hope it helps.

2 Likes