Building a documention site


#1

I have quite a content heavy site for my frontend framework which serves as documentation. However, now I have a problem. I just made a major refactor of part of the framework which means revising a number of pages, but the old version should still be reachable for folks still using that version.

Therefore, i need some way to switch versions of pages, something similar to a language switcher i think. I think I’ll have to take care of canonical links as well i think, and the sitemap.

I would like some ideas on how to tackle it. For now I can think of a couple:

  1. Clone the entire content into version subfolders (downside is its a complete clone, even if one page has changed).
  2. Duplicate pages and use tags, and use a language like switcher and a session storage to remember a users desired version across pages (feels messy to me).
  3. I cant think of a three.

Anyone got any awesome ideas? Thanks a bunch.


Made with Kirby and <3
#2

The third option would be to add stuff to the current documentation, giving it version tags (that’s what we currently do on the Kirby site). This is useful if you your version updates do not really justify clones (keeping the changes within the page without duplicating any content).


#3

Probably a wild idea but what if you actually use the language feature?
So something like this

c::set('languages', [
    [
        'code'    => 'v1',
        'name'    => 'Version 1',
        'default' => true,
        'locale'  => 'en_US',
        'url'     => '/',
    ],
    [
        'code'    => 'v2',
        'name'    => 'Version 2',
        'locale'  => 'en_US',
        'url'     => '/v2/',
    ]
]);

I have no idea if this works or not :slight_smile:


#4

I see. I just took a look at that. i’m not so keen on that idea, id like to be able to hit the page for a particular version, and have google index the different versions too.

I guess i’m just going to have clone everything, and use a session store and route maybe to go to the correct version across pages. How would I do that exactly?

Say my content was structured like this (im guessing the dots will be problamatic):

/content/v3.2.1/features
/content/v3.5.1/features
/content/v3.6.6/features

If i had a dropdown at the top of the with the versions listed in it, how do i store that in a session and pick it up in a route?


#5

Top marks for the wild idea… im guessing that might open up further problems, since kirby thinks these are languages. @texnixe is this workable do you think?

I like it because it means i can keep multiple versions in the same folder, but what happens if a page hasnt got a version for the one the user currently wants?


#6

Super quick test but looks like on my local installation is working fine.
29%20PM
“Languages” are displayed correctly…

23%20PM
And the files are created correctly

28%20PM34%20PM

Frontend is also working just fine


#7

Interesting idea, worth a try, I don’t know if it may have side effects, though.


#8

By default, Kirby will fall back to the default version. Unless you prevent it with filters.


#9

You’d need to modify the css in the admin a bit because of this:

'code' => 'v2.4.1'

55%20PM

But that’s an easy fix.
Can probably become a mess if you need to have dozen of versions


#10

Heh… good work, for thanks having a mess with it, I think maybe I will just go as far as 2.5 and forget the last digit.


#11

@manuelmoreale This turned out to be awesome, I’ve set it up for myself and it works a treat. The language switcher works fine too.

I am a happy bunny, although of course now I actually have to write the documentation… sigh


#12

O nice, glad to hear that. And good luck writing the documentation :wink: