[Feature] Versions

[stancl]

Soon, I will be releasing a 2.0 version of a package I maintain, and I need a version select dropdown on the top bar of my documentation site.

I want to avoid using a separate version of Jigsaw for each version, so adding this feature to the docs template would be ideal. Would you be interested in a PR?

A slightly painful thing I can think of with this feature is links. A helper function should be used since [Installation](/2.x/docs/installation) is ugly.

[mattstauffer]

Ahh that's super interesting! Could you show a bit of what your code looks like? We'd want to make sure it was still clean for anyone with only one version.

[stancl]

@mattstauffer I just finished implementing this and I have to say I'm not sure I can imagine how this could be implemented into this template in a way that doesn't make it a pain to have just one version.

The repo: https://github.com/stancl/tenancy-docs/tree/master/docs

Some highlights:

• the config file
• version select (and script)
• version-specific navigation in the navigation file and in the documentation layout
• folder structure: instead of docs/, I have 1.x/ and 2.x/
• this is how I make links - also used by the menu item partial

Even if this doesn't get added as a first-class feature, perhaps another example page could be added, with a tutorial on setting up versions?

[mattstauffer]

@stancl OK. maybe we link to either your repo, or we can write up a little segment on how to do it? We've been talking about a "how to do commonly-requested tasks" section of the documentation. This might be a great fit, if it is hard to incorporate it into the templates in a way that works for single-version docs.

Thanks so much for sharing this!

[stancl]

@mattstauffer I can either make a template repo like this one, or write a "tutorial" - like these - about implementing multiple versions and we could add that to the docs directory. I'd rather go with the second approach, because most people realize they need versions only after they've been using this template for some time.

[mattstauffer]

@stancl I definitely love the tutorial idea, if you're up for it!

[stancl]

@mattstauffer Does GitHub let you assign this issue to me? That would make me see it in my assigned issues.

[mattstauffer]

Done!

[damiani]

@stancl Great solution to doc versioning ... did you ever end up writing up a tutorial? If not, would you mind if I did and used your code as an example?

[stancl]

I didn't get to that, sorry, but yes absolutely feel free to use my repo's structure (should be stancl/tenancy-docs) in your example

[damiani]

Super, thanks!

[stancl]

FYI I'll close this since I don't plan on working on this, but feel free to reopen (& re-assign) if you'd like someone else to do this. Thanks!