Proposal: display multiple versions of docs

[anikethsaha]

versioning

Summary

Support for creating docs for different versions.

Motivation

Versioning support in a documentation generator is quite helping as it helps in supporting separating the docs for different versions. Helps is covering breaking changes. Improves readability.
There are other documentation generators that support this like docusaurus, gitbook etc.

Detailed Design

This will mainly require to make changes in the docsify-cli repo. I don't think we need any changes in the core.
We have great support for having navbar We will make use of that.

• Configuration

...
$docsify = {
  version : {
   // none I guess
 }
}
...

We can either make it to the navbar.

• cli command

docsify version <version> <path? = '.'>

This will do the following work in sequence

1. it will create a version with name <version> in <path>
2. check for the navbar markdown content i.e _navbar.md
3. if present, good to go. If not present, ask whether the CLI can create a new one or not. If the CLI is answered with no. Stop the operation
4. Update the _navbar.md by pretending the content with creating a new list versions. First, it will check whether versions are present as list heading or not. and inside that, append the list with the <version>. Use the AST for the markdown content in order to prepend, append, and check for the version list heading. (probably use remark)
5. it will copy-paste every files/folder present in the current directory from where this command is being run i.e process.cwd()
   to that folder i.e <path>/<version>
6. Done

Documentation

Create a versioning page in main docs. Create CLI command docs in the docsify-cli and either embed or do the remote rendering in the main docs in order to always show the latest docs

Drawbacks

Few cons or drawbacks

• it mandates the use of _navbar.md
• cant be customizable.
• <please comment if you find any>

Backwards Compatibility Analysis

Not required. As it will need changes in the cli not in the core.

Alternatives

Manually copy-pasting the files/folder and changing the _navbar.md

Open Questions

• do we want this on the sidebar? I tried but it was not looking good.

Help Needed

• Please provide some ( edge ) cases where this might break.
• Provide some suggestions to refine the proposal.
• At last, anyone wants to implement/take this ?

Frequently Asked Questions

N/A

Related Discussions

Forgot the repo + issue. But I did notice few issues and requests for this.

[Silthus]

First off: I think this would be a great addition and really helpful, especially if using something like semantic-release to auto create versions and package the correct docs with it.

One potentiell issue I see would be the linking of source files as examples. When using a git tag as the version there should be some kind of variable or variable replacement that allows to reference the correct file from the rev that is the version.

Here is an example:

I have an embedded code fragment I want to display in my docs and use the following syntax to embed it:

[filename](../src/app/js/example.js ':include :type=code :fragment=demo')

What would this display after the cli version command copied all of the files? Always the master branch? Will it be copied as well? If yes, where?

One solution to this (I can think of) would be to add a ref tag to the embed snippet that defaults to master, but also takes a variable that can be resolved to the current version.

[filename](_media/example.js ':include :type=code :fragment=demo :rev=$version')

What do you think?

[anikethsaha]

I am not planning of using tags for versioning instead, using folder structure. So whenever versioning is being done, you will a new folder named <version name/number> and inside that everything will be the same as it was before the versioning.

[MarvinJWendt]

Hi, in my opinion there should still be an option to convert git tags to docsify versions. In the long run, you could for example provide a GitHub action that updates the versions with docsify-cli on every tag pushed to GitHub. There could also be a dev version, which contains the documentation of the current master branch.
Of course, the difficulty here would be to automatically generate the documentation up to a certain tag.

The steps that would be necessary for this:

1. docsify version is executed
2. docsify gets all git tags by executing git tags
3. for each tag:
   1. git checkout tag-name
   2. the documentation is generated and temporarily stored
   3. git checkout master
   4. the documentation is saved in /docs/tag-name
4. here follows the _navbar.md generation, but @anikethsaha has already described it.

Creating a GitHub action would be easy with this functionality and would automatically list each pushed tag as a new version in the documentation, which would eliminate the struggle to update the docs versions manually.

[jthegedus]

@anikethsaha While a nice solution, that would create quite a large impact on repo size over time. Tools that use git as their underlying versioning system would increase the volume of code served to their users as the documentation changes across versions might generate a small or zero git diff but large size when measured by a simple copy.

[anikethsaha]

@MarvinJWendt Github action sounds great helper.
@jthegedus yeah , you have a good point about the repo size. Thanks for bringing this.

Can you guys create a polished proposal for your solution? I would love to read them and we might change this proposal to the new one if that fits well. You can comment here with the above template.

[jthegedus]

I have no idea if this is feasible.

Design (not so detailed)

My initial thoughts were that given we have the Repo URL and the filepath within a given folder that we could fetch the files via git tag as we would for files like https://raw.githubusercontent.com/docsifyjs/docsify/v4.11.5/README.md.

The complexity is how Docsify would reload to re-render these files while keeping the configuration of the user's selection. Perhaps via query params or localstorage.

So for a homepage we would get:

• on initial load: https://raw.githubusercontent.com/docsifyjs/docsify/master/README.md
• after selecting a version: https://raw.githubusercontent.com/docsifyjs/docsify/v4.11.5/README.md

Perhaps this can be taken care of with the existing basePath configuration where it gets rewritten on version select?

The actual list of versions would need to be populated by performing a fetch to the listed repo's platform's API. EG: GitHub https://docs.github.com/en/rest/reference/repos#list-repository-tags

The value I (and others in my circles) get from Docsify is the fact it doesn't require a redeploy each time docs change. It's all client-side and set and forget. If we can provide versioning support in the same way that would be ideal IMO.

Other

• users could define the default tag to be master or a version number if they wish to pin to a stable release of their tool
• requires a full reload for Docsify to render the selected version of pages (unsure if this would be different from the initial proposal)

[psa-jcjaillon]

Hi,

Maybe we could just create a branch (called "docs"), containing a docs/version-xx.xx directory, including only documentation in html format ? (not markdown)

[FaultyFunctions]

Any developments on this proposal?

[Piotr1215]

Hi everyone, thanks for the amazing tool. Any progress on this proposal? This feature would be really useful.