Use git tags for versioning

[DanielMSchmidt]

Is this a bug report?

No, a feature request.

Have you read the Contributing Guidelines on issues?

Yes

Environment

Environment agnostic

Steps to Reproduce

1. Add Docusaurus to your project
2. Release a new version and create a versioned documentation
3. Get "annoyed" by all the information that is stored twice, for each git tag and also in a seperate directory

Expected Behavior

I would like to be enabled to use docusaurus in a mode that gets the git tags of this repository and gets the documentation at that point of time. I am aware that using this version we would opt-out of changing the docs after setting the tag (without changing the tag), but this might be okay for some use cases.

Actual Behavior

Duplicately stored versions of the docs

Reproducible Demo

I have no demo, just a PR against wix/detox mimicing this behaviour. I would like to move this upstream to this repository in a well-tested way. See this PR: wix/Detox#582

[juliedavila]

I would really like this

[pke]

@endiliey Why was this closed? It would be a really neat feature. Creating subfolders for versions is a lot of extra work for things git already knows. Could this maybe implemented via plugin?

[slorber]

Hey

Docusaurus encourage the usage of versioning on a single Git branch, but nothing prevents you from reverting to the old more usual behavior of having multiple Git branches for each version.

In fact, it's possible to use a hybrid (Git branches + versioned folders), and this is exactly what we do ourselves for Docusaurus v1:

• https://github.com/facebook/docusaurus/tree/docusaurus-v1
• https://v1.docusaurus.io/

Notice also that older v2 alpha/beta versions (that we do not update anymore) have been archived to standalone immutable static deployments, and remain accessible forever.

https://docusaurus.io/versions

Docusaurus only encourage you to use a versioning pattern, but it does not lock you into it.

[pke]

I checked how Docusaurus does this but our scenario would be in a trunk based environment with git tags. And we would like to generate versions based on git tags on that branch.
Would that mean, that we compile a static version of the docs and commit this static version to git?

So the current version is generated from current trunk HEAD and all other versions live under /versions?
So say we are at Version 1.0 and now create a version 1.1.
Before we increment the version to 1.1 we compile the docs from trunk into versions/1.1 and commit that to git and tag everything with 1.1?

[slorber]

If you have multiple branches, you can simply configure your host to deploy those multiple branches.
Each version/deployment can have its own independent versioned subdomain.
If you want to host everything under a single root APEX domain you can use the host reverse proxy features so that v1.x.com is served from x.com/v1

I'm not sure it's possible to deploy a tag. If you deploy a specific git sha, you can just build it locally and upload the static files manually once and it will stay online forever.

All this is outside the scope of Docusaurus. We just build static files, and there's a lot of different way to serve them.

You can as well archive older deployments to static/v1 on main if you want, really up to you and your organisation practices. IMHO It's not worth to commit such older version static files to Git, as it increases the repo size uselessly. You can just publish an older doc to an immutable standalone deployment, like we do:

• https://v1.docusaurus.io/
• https://6290e4c00805dd0009fb3080--docusaurus-2.netlify.app/docs/2.0.0-beta.19