Question: Does this theme support versioning?
Closed this issue · 13 comments
Understanding that software moves through versions over time, does this theme support having different versions of the docs?
I'm looking at the original theme, and it looks like they support an optional drop down where the user can select a version (see here https://www.docsy.dev/docs/adding-content/versioning/). However I don't think the versions are all within one docsy rendering, note that it says:
How you deploy the previous versions is up to you.
It seems like it's just separate versioned URLS. So what that would mean here is redundancy - actually deploying different GitHub pages for the different versions, and then making them seem unified by way of that dropdown. It's not such a crazy idea, although it does require more than one repository, potentially, unless you can figure out a strategy to have the theme under one root?
I'd be happy to add a similar data file to hold versions, and then display that dropdown if it's filled in. Do you have any ideas for how the different versions could be supposed for one repository?
@leecalcote I looked into this a while back. The docsy jekyll theme doesn't inherently support versioning but as @vsoch said, it can be done with some manual configuration by adding a separate config file. Have a look at this -
https://justwriteclick.com/2017/07/30/investigating-jekyll-for-versioned-content/
The one drawback to going with this approach is that we would need to manually update the config file at regular intervals. But perhaps that can be automated as well 🤔
I think we should also follow this issue google/docsy#114. As soon as something is implemented for support of different content in some folder structure, I could possibly mirror it here. But for now, if someone can find a rendered site that has the "versions" tab working, that would be enough for me to add that functionality here. But again, it would still be up to you to handle generating links for the different deployments.
Another ide off the top of my head, a really stupid idea would to maintain the same _docs folder structure, have the current content at the top level, but then have version subfolders with whatever version string you would want. E.g.,
_docs/
getting-started.md
v1.0.0/
getting-started.md
Meaning that the main getting-started guide would be at docs/getting-started and version 1.0.0 would be at docs/v1.0.0/getting-started. And then if there was still some metadata file somewhere for versions:
versions:
- v1.0.0
That could feed into a selector at the top of any page to add the version prefix to the URL. If the page exists for a previous version it would render to it.
And note that you could also enforce all documentation to be under a verison, and then have some top level page be a navigation to that:
_docs/
versions.md
latest/
getting-started.md
v1.0.0/
getting-started.md
could add versioning in through release system and automated via jekyll generation/github actions? branches as needed?
Are you asking about versioning provided by the docs, or the code here? You you clarify what you want and your suggested approach?
Docusaurus takes an approach to versioning similar to that proposed above: https://v2.docusaurus.io/docs/versioning
I would also (highly) recommend deploying to readthedocs for nice versioning. It's harder to do on GitHub pages.
hey @leecalcote @smoyergh @neotamias @chandrashritii we have PR open that will add versioning if you'd care to review! -> #69
@vsoch bless! Thanks for this update! Will be using this when I relaunch my site.
Awesome! I'll be reviewing soon (and hopefully others can take a look) so I'm hopeful we can get these changes in soon!
It does now! -> https://twitter.com/vsoch/status/1541565138494320640 and y'all head over to #69 to give @steve-lyons some appreciation 🙌, thanks 🙏 and love! 💞