Add switcher to switch between various .md files for versions, languages, etc.

[dmyers]

Do you have any thoughts on how you could have multiple API versions? It would be kind of cool to somehow do it based on folder structure and how the shell/ruby/etc switching works maybe.

[lord]

Hadn't thought about it, no. Any ideas? I'm open to suggestions, but also prefer ideas that keep Slate relatively simple and straightforward.

[ApoorvSaxena]

As versioning applies to the entire documentation, it better be placed on the top with a dropdown(if required). Also, header can be used to place other important links which are currently a part of the left sidebar.

[ApoorvSaxena]

Another possible solution is to place the version control information on the left hand side, enclosing the resources that get affected due to versioning.

[lord]

Ah, hmm, and perhaps the dropdown would link to other .md files in the Slate project? I like this idea. I definitely think the sidebar would be a good place for that, too. I'll try to hack something up on this when I get the chance.

[ApoorvSaxena]

Have implemented the above prescribed solution in design, you can checkout this repo to start with.

[lord]

Thanks for the submission, I'll look into it when I get around to implementing this.

[natebird]

I’m also interested in seeing this implemented.

[natebird]

@ApoorvSaxena The repo link provided above links to just a forked repo without any changes (at least I couldn’t see anything different). Maybe they weren’t pushed? Thanks…

[lord]

@natebird I believe @ApoorvSaxena put the changed code in a different branch of that repo.

[natebird]

I see that. Thanks!

[s12chung]

@lord when do you think this will be implemented? thanks.

[lord]

@s12chung I unfortunately can't give a definite time, but it's on my todo list.

[oubiwann]

+1 for this feature; crucial for my projects.

[sman591]

+1, it's a requirement for my current project

[oubiwann]

I got around this via a deployment hack.

Basically, when I tag a new release, I generate the site and move it into a "master" docs directory with a dirname matching the version. The index.html file there is a metarefresh to the current docs.

You can see it in action here:

• http://lfex.github.io/lhc/current/

(note there seem to be unrelated issues with focus and hover, with nav items getting selected incorrectly ... I'll poke around in the other bugs and see if anyone's reported this)

Update: the issue with the nav items not being selected properly seem to be #280.

[rixx]

+1 very interested; both API versioning and multiple languages would be very nice (and good practice for documentation).

[thomax]

@lord Are there any plans for releasing this feature? If not, mayhaps there is an alive and healthy fork where this has been implemented?

[lord]

Yes! It is planned, but there is no current timeline.

[jonomacd]

Just wanted to +1 this feature as we need it as well. Thanks!

[seweil]

We are interested as well. Our scenario: Complex API is pushing the perf and usability limits of one tall page. I'd like to split it into a few major sections.

[seanwendt]

+1 as well, updating our API but would like to keep documentation for both V1 and V2 available on the same single-page app. I like the idea of the drop-down to toggle between versions. In the meantime, I've simply deployed a custom index.html landing page, and copied /source into two version-specific folders: /v1 and /v2. index.html simply has hyperlinks to "/v1" or "/v2".

[lord]

As another note for future reference when this is implemented — #679 suggests a hierarchy of pages might be nice, instead of a simple dropdown switcher.

[qB0t]

Any updates on this one? Would be great to have for multilingual documentations.

[P1llus]

Yeah i second this one, seems very interesting! If not only for API versions, it could also be used if you document different versions of software..

An example would be to be able to tag each API call you document with a version tag of the software it is supported on (one or more). Then let the user pick which version(s) he want's to see.

[zramsay]

+1 yeah this would be really helpful. I'd be happy with a feature that works just like Read The Docs:

[ProElbs]

Hello ! Hope you are having a good day !

Any news about this feature to be able to version API doc?