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.

[my9074]

@janvennemann In some docs, we need to display the dynamic version number. After version control is implemented, can you satisfy the variables that reference the version in the document fragment?

[jankeromnes]

Hello! 👋 I think you meant @janvennemann. 🙂 Deferring the question to them.

[janvennemann]

@my9074 Usually you access the version of a particular page via $page.version. However, I don't think that's easily done in your particular case since it is inside a fenced code block that will be pre-rendered and you don't have access to Vue interpolation there.

There may be a fancy solution using script hoisting and then search & replace a marker with $page.version but i haven't actually used that yet. You easiest bet is to manually maintain the correct version number in your fenced code blocks.

[about-code]

Just a side-node (or user story): Collaborative docs are often maintained in a VCS like git, on GitHub, or Gitlab servers where you tag a revision of your source tree. From GitHub or GitLab you can directly clone/pull tagged versions of a documentation via URLs.

The OP seems to use the term tagging as adding a new versioned subfolder. If I use the term tag below I refer to git tags, so labels for a particular commit or state of a repository.

While an RFC certainly needs to specify the directory layout for building, thus including version directories makes sense, it would be cool if a final implementation would be able to pull these versioned directories directly from git tags. Then anything apart from master could be .gitignore-ed. Version state wouldn't become part of the source tree. I think of something similar to what Antora does, for example.

Otherwise it may happen to have a commit with a v2.6 version folder on a "master" branch being changed after a v2.6 git tag has been set on an earlier revision. This undermines git tags, effectively and also makes diffs between versions a lot harder.

[janvennemann]

Interesting use case! This would require some kind of branch management and logic to merge the docs from different branches into one big final build. Although probably possible with the really powerful plugin system, IMHO that complicates things by a certain degree. However, definitely an interesting alternative to having the versioned docs all checked into one branch.

[robsontenorio]

For reference, take a look on this repo https://github.com/nuwave/lighthouse It is a php package with a “/docs” with vuepress things. On there we just wrote a simple versioning mechanism. All the docs related things including vuepress and versioning are in “/docs”. There is a small readme on “/docs”. Em ter, 24 de set de 2019 às 08:40, Jan Vennemann <notifications@github.com> escreveu:

Interesting use case! This would require some kind of branch management and logic to merge the docs from different branches into one big final build. Although probably possible with the really powerful plugin system, IMHO that complicates things by a certain degree. However, definitely an interesting alternative to having the versioned docs all checked into one branch. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1018?email_source=notifications&email_token=AAA5BK3R7HS3AUQBSU4WO5LQLH4CLA5CNFSM4GE5VK7KYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD7OB26I#issuecomment-534519161>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAA5BK7CG6I23M5HQ2NBHCLQLH4CLANCNFSM4GE5VK7A> .

-- — Robson Tenório

[about-code]

@janvennemann

This would require some kind of branch management and logic to merge the docs from different branches into one big final build. Although probably possible with the really powerful plugin system, IMHO that complicates things by a certain degree.

I think there could be different incremental steps.

1. The first stage paves the way for a minimal solution satisfying the core use case. It compiles docs from version folders, no matter how they are being created, manually or via some kind of checkout. The proposals so far seem all equally well suited for solutions likely to provide enough added value for many people.
2. In a second stage 'on top' of this first stage prebuild scripts may be added which are capable to detect whether there's a .git folder, and if so to recreate the vX.Y-folders from the git history. They could be using the git CLI to find out about tags, tagnames and to restore a particular commit state from the current repo clone, since all info is in its history.
3. A third stage might add full branch support, if there's demand for and developer capacity. Personally I'd already be happy with a stage 2 feature.

Said this, all three stages would be worth their own issues, so I aggree with keeping this one the thread for kind of a "stage 1" solution.

[smrbts]

Any word from the Vuepress team if this is something they have on their radar for the near future? Really enjoy using the default theme for our docs, but the lack of versioning is really going to be a problem moving into the future.

[metasean]

It looks like the RFC process is now in place (https://github.com/vuejs/vuepress/tree/master/rfcs).

@robsontenorio , @janvennemann , & @about-code - Y'all look like you have the most fleshed out concepts. Any chance one of you is willing to start the RFC process?

[robsontenorio]

For me it is ok if you copy and past this issue on RFC board. But at this time i am sorry not being available anymore to implement this feature. Em ter, 5 de nov de 2019 às 18:22, metasean <notifications@github.com> escreveu:

It looks like the RFC process is now in place ( https://github.com/vuejs/vuepress/tree/master/rfcs). @robsontenorio <https://github.com/robsontenorio> , @janvennemann <https://github.com/janvennemann> , & @about-code <https://github.com/about-code> - Y'all look like you have the most fleshed out concepts. Any chance one of you is willing to start the RFC process? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1018?email_source=notifications&email_token=AAA5BK3Z52IQYHBT42JL74LQSHPZTA5CNFSM4GE5VK7KYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEDELYOI#issuecomment-550026297>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAA5BK6K6DLUM6BRTCVVDIDQSHPZTANCNFSM4GE5VK7A> .

-- — Robson Tenório

[about-code]

@robsontenorio , @janvennemann , & @about-code - Y'all look like you have the most fleshed out concepts [...]

Hmm, I wouldn't use the terms fleshed out or concept myself ;-). My ideas have really just been ideas :-)

[metasean]

Anybody interested in this, please help flesh out #2018 with your ideas, concerns, interests, etc.

[axieum]

Another thing to take into account, is the combination of locale and version. I believe the URL should show as en-GB/1.0/*, but the file structure should be 1.0/en-GB/*. This may cause issues with the VuePress path resolving as the URL would not reflect the relative path.

[arvindanta]

Can we inject scripts in the head based on the sidebar route ?

I have the below sidebar config. Can I Inject particular version of script for each sidebar route ?

      {
        '/v2/': [ { title: 'Getting Startedv2' }, { title: 'Getting Startedv21' } ],
        '/v3/': [ { title: 'Getting Startedv3' }, { title: 'Getting Startedv31' } ]
      }
    ,```