[feat] docs versioning

[thibaultcha]

This PR has a little Jekyll plugin which injects some versioning infos into variables:

• page.kong_version (into documentation pages only)
• site.data.kong_versions a list of all versions available
• site.data.kong_latest the latest version of Kong

versions.yml is just YAML so we could extend it later to add properties to versions such as stable: true etc...

This versioning raises some questions:

1. should the version of the docs should always be visible in the URL or not?

For example with two versions 0.1.0 and 0.2.0:

/docs/0.1.0/how.html
/docs/0.2.0/how.html

or

/docs/0.1.0/how.html
/docs/how.html

or

/docs/0.1.0/how.html
/docs/latest/how.html

Have to see if those are possible and how to implement it ^

1. Should the screencasts be versioned too? I guess yes (cc @thefosk)
2. Should the downloads be versioned too? My guess would be yes again because we might have, say a new package manager in a new version for example?

If yes to 2. and 3., then what is their URI? URIs are versioned only under /docs/, so it would be:

/docs/0.1.0/download.html
/docs/0.1.0/screencats.html

1. We need a list of all versions available somewhere (with links. Like a dropdown). Currently @jitachi suggested a dropdown on top of the sidebar.

[thibaultcha]

oops.

[montanaflynn]

For how to hadle versions in the URL I propose to have the latest alias in addition to all the versions, similar to how elasticsearch does it.

http://www.elastic.co/guide/en/elasticsearch/reference/1.3/search-aggregations.html (older version)
http://www.elastic.co/guide/en/elasticsearch/reference/1.5/search-aggregations.html (latest version)
http://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations.html (alias to latest)

[thibaultcha]

I agree. Though I don't see a way to do that yet with Jekyll, without the help of a custom plugin again. Because what we want is to duplicate the content of, say 0.2.0 to also be in a folder named current.

Otherwise we could not do an alias but rather a redirection using something like jekyll-redirect-from but this is how redirection is done https://github.com/jekyll/jekyll-redirect-from/blob/master/lib/jekyll-redirect-from/redirect_page.rb and the URI will be rewritten from current to 0.2.0 when landing on the page.

For now, I see no other choice but to duplicate the generated content to have a real alias.

[montanaflynn]

A 302 redirect might actually be better for SEO, because with an alias we would have to add a canonical tag, but that would change as we release new versions.

Also what do you think is better, latest or current? And what about tagging releases as stable? Whatever we decide as for naming it should be consistent with whatever @jitachi designs for the UI to switch between them.

[montanaflynn]

+1 for downloads and screencasts (and articles / tutorials...) being versioned as well.

Having the url be under /docs/ makes sense to me. Since some pages may have their own design (E.g. the download page which has no sidebar) I think the version switcher needs to be in a global layout element like the header.

[thibaultcha]

A 302 redirect might actually be better for SEO

But we cannot do that with a Github Pages website afaik. And the example I posted does use the canonical tag. If we want a proper redirect we need to host the website ourselves behind some nginx and configure it for each release to update the current alias.

I prefer latest. It is also what Docker uses in their doc (not in the URI but in their dropdown).

[ahmadnassri]

this might not be a smooth way of getting 302s, but:

you could (in fact you should, for many other reasons) have the entire site behind Cloudflare, there you can setup redirect rules, with custom redirect status codes.

[thibaultcha]

Mhhh yep, works too I guess

On Apr 4, 2015, at 5:35 AM, Ahmad Nassri notifications@github.com wrote:

this might not be a smooth way of getting 302s, but:

you could (in fact you should) have the entire site behind Cloudflare, there you can setup redirect rules, with custom redirect status codes.

—
Reply to this email directly or view it on GitHub.

[thibaultcha]

It'll be a pain to update the redirect settings at every new version.