Ability to turn off the "next" version / make editing docs easier

[joshribakoff]

💥 Proposal

After cutting a version (eg 1.0.0), the docs exist at both docs/ and versioned_docs/version-1.0.0. If for instance, I want to fix a typo, it seems like I would have to edit both copies anytime a change is made?

It seems like the versioning feature presumes I want a next version. However, I only just released 1.0.0 with no breaking changes under development, so I don't need or want a "next" version, as it's just another place I have to maintain, and an additional point of confusion for my users.

Also, I'd like to be able to work on the structure of & improve my 1.0.0 docs, without having to create a new version of my library.

As a workaround, I have to make sure if a file exists in both folders to edit the "versioned" doc, and then run rsync -avr ./versioned_docs/version-1.0.0/ ./docs/ to make sure next (which I don't actually want) stays updated. Or another workaround is

➜  rx-store-website git:(master) rm -fr versioned_docs/version-1.0 versioned_sidebars/version-1.0-sidebars.json 
➜  rx-store-website git:(master) ✗ ../../node_modules/.bin/docusaurus docs:version 1.0      

One way to solve this would be to update versions.json with a 1.0.0 entry, but have it point to "docs" folder. Only later if & when I cut a new version would the "versioned docs" for 1.0.0 be added, so it'd archive a version at the time it reaches end of life instead of when the version is released would be an improvement IMO. I think it'd also have to invert the diffing to work (eg, archive everything, since you don't know what will change in future versions, then later when you archive another version on top of that is the point in time in which you'd prune files from the older versions that did not change)

Have you read the Contributing Guidelines on issues?

yes

[slorber]

Hey, this is a known problem that many have, that I plan to solve with this RFC: #3285

The idea would be in your case that, when v1 is ready to be published, you don't version it immediately with the cli, but instead you keep it in ./docs, and the config allows you to define the label/path of the current version, so that you can have "Version 1.0.0" at path /1.0

Only when you start working on v2 docs, you would use the cli to archive the v1 docs, and need to maintain 2 separate doc sets.

We'll also add an option to simply turn off the "current" version (/docs) if you want to.

I'm closing but feel free to tell me if the RFC does not cover properly your usecase, but I think this case will be covered properly. The goal is to make doc contributions easy, so that we don't have to unnecessarily ask contributors to backport their changes in /docs to versioned_docs/version-1.0

[joshribakoff]

I've bookmarked the RFC to read later, what you described sounds exactly like it will solve the issue, and the workarounds I posted in the OP seem tenable in the meantime, so it is fine to remain closed. Thanks!

[slorber]

great to know

It's probably out of scope, but in addition to the notes I left on #3294 one other thing I wanted to point out that's worth considering that as a user I'd maybe like to include code snippets on my home page, which could differ between versions.

Answering there as I think it's out of scope of this RFC:

pages are not versioned, and is decoupled from the docs plugin, so you'd have to implement this on your own, because pages know nothing about versions

[joshribakoff]

pages are not versioned, and is decoupled from the docs plugin, so you'd have to implement this on your own, because pages know nothing about versions

Yep, I'm aware. I would suggest changing it. Maybe there is some reason not to change it, though. The way it could work is to designate the website's home page as a page supplied by the docs, so its managed under the docs plugin but mounted on the root route.

Right now I see it as a limitation, not a feature, as a user I don't really care/want there to be any difference.

Feel free to take my feedback with a grain of salt obviously, but I just wanted to share my honest feedback. Ya'll are doing a great job :)

[slorber]

I don't really understand your suggestion sorry 🤪 can you be more concrete?

The way it could work is to designate the website's home page as a page supplied by the docs, so its managed under the docs plugin but mounted on the root route.

It's already possible to use docs-only mode for that, where a doc is at the root of your site: https://v2.docusaurus.io/docs/docs-introduction/#docs-only-mode

Also if you want to can create src/pages/v1/myPage.jsx, and src/pages/v2/myPage.jsx already, and have totally different code. I don't see what we can do to improve that experience.

[joshribakoff]

Sounds like you already have the feature I was suggesting then and it just wasn’t super obvious. I’ll try it out again in the future. For now I turned off versions because it was a bit cumbersome to edit the dupes files. Thanks for the reply!