Docsify: Versioned Documentation

[emersoncloud]

Is there a way to create versioned documentation? I have been searching around and found this issue: #572 which mentions different versions. Also this ticket #341 asking for rendering from different branches.

I can't find anything in the Docsify docs talking about versioning.

Thanks!

[alexlee-dev]

I would also be interested in this. I don't know if it currently exists with docsify.

[jsmedmar]

Ha this seems to be a great challenge only yet solved by sphinx / Read The Docs. People at mkdocs have been struggling with this since 2014. I love docsify, but versioning the documentation seems very important to me at the moment. Although some big projects such as Django Rest Framework don't seem to support versioned docs. jimporter wrote a solution called mike for mkdocs perhaps that could serve as a starting point.

[timaschew]

As long as docsify will render stuff on the fly there will be no guarantee that older documents will be rendered properly due to breaking changes.

Nevertheless it's possible to achieve this, but not by fetching the content of older documents from a repository. I actually like the idea of mike in terms of immutability and it's good that this is an own tool, because your documentation tool should not rely on anything git related. Of course readthedocs is an exception because it's service, not a CLI which you run on your local machine. I mean the whole infrastructure is based on a repository.

Anyhow for docsify we can define a configuration file which allows define a map (version -> zip) for older versions. The archive can be extracted in the browser on the fly which would require lot of refactor. Alternatively we extends docsify for a optional build step which is handling the extraction in order to avoid logic to render pages of a zip on the fly.
How you create the zips for older versions is up to the user. You can create them via GitHub. If something is rendered wrong you can fix it and upload a fixed version somewhere else. But if we have a build step in doscify and it can prerender static files then we can even generate the older docs even with a previous version of docsify, exactly the one which was used those times. At the end it will be the same logic as mike is doing it.

[Rapster]

Would it be possible to use docsify with git tags to fix that ticket? I don't like creating folders per version as it congest the repo and plus, it some sort of duplication since docs are already versionned by github itself

[anikethsaha]

This is something which would be really interesting. I wont go for any repo related op cause its quite hard to achieve and many docsify users uses different repo management sites to host their docs

What I am proposing is

CLI

Command :

docsify archive -v=10.3

What it will do ?

It will create a folder inside docs as old_docs (or something more appropriate name) and then it will copy the current docs inside this folder with name docs_10.3

docs/
  |- old_docs
      |- docs_10.3
           |- index.html
           |- _sidebar.md
           ...
  |- index.html
  |- _sidebar.md
  ...

it will create an _archived _docs.md file which will contain the metadata in order to render a drop-down or something in the header. which when clicked, docsify will read/render contents from old_docs/docs_10.3 folder as docsify would do its own operation. we will use the alias config to configure correctly the archived docs.

main docsify library

Making support of _archived _docs.md to render as dropdown or anything else.
Also, I think we need to make the alias in runtime.

Performance

• I dont think there would be any major performance slow down than the folder size increased.
• When rendering old docs, it has to generate the alias and then render the old archived docs so we may see a bit slow down there

I think we can consider this feature for 5.x but we need to have some PoC first in order to discuss it better.

cc @docsifyjs/core @trusktr @jamesgeorge007

[Silthus]

Would there be an option to specify the tag or version as a variable inside the URLs that are used to fetch remote content or source files?

This would be very helpful to fetch the related documentation and examples based of the version tag from a specific repository.

[anikethsaha]

There is an active proposal https://github.com/docsifyjs/docsify/issues/1289