Versioned guides

[jwoertink]

Right now the guides only show docs on the latest released version. The next version of Lucky to be released will change a lot of those docs. Eventually we will need a way to display docs based on specific versions.

This can probably hold off until things become more stable (especially with Crystal), but I figure we might as well get an issue about it.

[stephendolan]

@jwoertink Have we thought about perhaps tackling this with sidecar markdown files that the base action interprets? I'm almost wondering if we had a structure like this, whether it would be an elegant way to handle versioning:

authentication
├── api_authentication.cr
├── api_authentication_v_0_22_0.md
├── api_authentication_v_0_23_0.md
├── api_authentication_v_next.md
├── browser_authentication.cr
└── intro.cr

Then perhaps the base .cr file could look up the appropriate version and dynamically load the right markdown content to be rendered. I could see if I could get a proof-of-concept working in a PR, unless there was a set of options that had already been considered.

Another advantage this would provide is more robust markdown linting, so that we could enable something like Prettier for all of our Markdown documentation.

[paulcsmith]

@stephendolan I think the only downside to that approach is you need an action and markdown file which I think could get tedious. Or maybe I'm misunderstanding/not seeing the big picture. I'd be down to see a proof of concept if you think it would work well!

My initial thought that may be a bad idea is to do roughly:

• Duplicate the src/actions/guides folder
• Rename it to src/actions/guides/vX.X
• Find and replace to add version number to path for actions in that folder

However, I've not thought this through that well so this could be a bad idea! Just want to throw it out there in case it sparks some ideas

[stephendolan]

@paulcsmith That's definitely a fair criticism and downside to this approach... I will say, though, that from a "pure Lucky" perspective, it actually might feel more intuitive if each guide Action in src/actions/guides had a corresponding markdown Page in src/pages/guides...

I definitely see merit to the version namespacing happening in the path as well, it just might end up with a bit more custom fallback and routing logic to get where it needs to go (maybe?).

[paulcsmith]

@stephendolan Yeah that's a good point. Maybe more "Lucky" like, but it is also a bit strange to have an action per "static" file since all it is doing is rendering.

I'm not totally sure what the best approach here is so if you wanna do a proof of concept that'd be great, but understand if not. It's probably pretty time consuming so I understand if you don't have time to tackle this