Docs versioning mechanism

[robsontenorio]

Feature request

https://docusaurus.io/docs/en/versioning

You can use the version script to cut a new documentation version based on the latest content in the docs directory. That specific set of documentation will then be preserved and accessible even as the documentation in the docs directory changes moving forward.

What problem does this feature solve?

Create a mechanism to tag versions of docs.

What does the proposed API look like?

Tag a new doc version

yarn run version 5.7

This generate a new folder with tagged docs and includes a dropdown with all available versions. Must be added on default theme.

How should this be implemented in your opinion?

Mostly like Docsaurus does.

Are you willing to work on this yourself?**

No.

[ulivz]

This is indeed a useful feature, but implementing it must cause breaking changes, first put it aside, and we will introduce RFC process to discuss implementation details.

[luisDanielRoviraContreras]

+1

[robsontenorio]

@ulivz I am considering working on this. Can you provide some guide lines in order to avoid breaking changes?

Implementation

In this example didnt touch on core components or core vupress files. Just implement a side lib to make it working. The idea is that can be placed on core system and adjust core components in order to get better integration between search and docs versions (in order to avoid search duplications). Or maybe create a new core component SearchDocs (searchbox + docs dropdown)

Branch

https://github.com/robsontenorio/lighthouse/tree/vuepress

Latest preview

https://5bf559de05c4170ceead6d8f--lighthouse-vuepress.netlify.com/

Directory structure

docs/
├── .vuepress/            
│   ├── config.js         # global site config
│   └── versions.json     # auto-generated versions file
│
├── master/               
│   ├── guides/         
│   │   └── auth.md       # http://mysite.com/master/guides/auth.html
│   ├── the-basics/         
│   │   └── fields.md     # http://mysite.com/master/the-basics/fields.html
│   │ 
│   └── sidebar.js        # versioned sidebar for this version   
│
├── 2.6/               
│   └── ...               # same structure from "docs/master/"
│
├── pages/
│   └── ...               # Not versioned, it remains the same for all docs versions
│
├── package.json          # vuepress dependencies
└── INDEX.md              # the beauty home page

Files

Creating new files

1. Place the new file into correspondent version folder.
2. Include the reference for the new file into correspondent sidebar.js, according version number.

# the new file
docs/3.1/guides/cruds.md

# edit the correspondent sidebar
docs/3.1/sidebar.js

Linking files

• Remember to include the .md extension.
• Always use relative paths according to folder structure.

The [@paginate](directives.md#paginate) directive is great!

See the [Tutorial](../getting-started/tutorial.md) for more info.

Versions

Each subfolder in docs/ will represent a documentation version, except docs/pages/ that will remain the same for all docs versions.

Path	Web route
docs/master/guides/installation.md	http://mysite.com/master/guides/installation.html
docs/2.6/guides/installation.md	http://mysite.com/2.6/guides/installation.html
docs/pages/users.md	http://mysite.com/pages/users.html

Updating a existent version

You can update multiples docs versions at the same time. Because each docs/ subfolder represents specifics routes when published.

1. Edit any file.
2. Commit and push changes.
3. It will be published to the correspondent version.

Example: When you change any file from docs/2.6/, it will publish changes only for 2.6 docs version.

Tagging a new version

1. First, finsh your work on docs/master . A version always should be based from master.

2. Enter a new version number

yarn docs:version 3.1

1. Commit and push.

2. It will be published as the last documentation version.

When tagging a new version, the document versioning mechanism will:

• Copy full docs/master/ folder contents into a new docs/<version>/ folder.
• Place a new version number in docs/.vuepress/versions.json

[maziarz]

Any update on this issue? Would really like to contribute where possible, as i am depending on this feature.

[amimas]

Is this feature being considered for the next version (1.x)?

[nklayman]

Now that 1.0 is released, could this be created as a plugin? The plugin api appears to be quite powerful as there is a blog plugin. @robsontenorio would it be possible to move your work to a plugin?

[janvennemann]

We have been working on a plugin that does versioning in VuePress. It's still in the early stages but we released a first version a couple of days ago. It's pretty similar to how Docusaurus does versioning so there are a few differences to @robsontenorio approach.

Overview

• Docusaurus style versioning ported to VuePress
• vuepress version <sourceDir> <versionNumber> command to draft new versions
• Current version of your docs stay in the VuePress source folder. A snapshot of your docs will be copied to website/versioned_docs when a new version is created. Also snapshots your current sidebar config and stores it with the version.
• Configurable extra pages folder for unversioned documents (under website/pages by default).

Guide and Demo

Please check out the guide and demo of the plugin here: https://titanium-docs-devkit.netlify.com/guide/versioning.html

The plugin requires a modified theme that is able to handle versioned pages to properly generate links, which you can also find under the link above.

Known issues

• Permalinks are currently not supported. Paths for pages will be changed based on what version the page is part of. The permalink option is currently ignored during that process and results in duplicate pages.
• Not tested yet with other major plugins, like the blog plugin for example.

[florimondmanca]

That sounds promising @janvennemann!

Extra pages folder under website/pages for unversioned documents.

Would it make sense to store versioned content in a dedicated folder, instead of non versioned content? This would allow to have extra pages anywhere and not place any extra constraints on folder structure. My intuition is that this could make discriminating versioned content easier as well. :-)

[janvennemann]

In our use case everything in the docs source folder needs to be versioned anyway and only a few extra pages are exempt from that. That's the reason we choose it that way around. The folder website/pages is not hardcoded btw and can be configured in the plugin options.

But i see that for others only a specific folder could be of interest to be considered for versioning. I already thought about a exclude/include kind of option which could probably allow that. I'll put that on the todo list.