3

I'm trying out Docusaurus tool for creating a documentation site. So far everything is okay until I came to Versioning.

My understanding is that:

  1. Whatever is in your /docs/**/*.md is your latest docs for next release
  2. Previous versions of your docs are available in /website/versioned-docs/version-${version-number} directory

What is not clear to me is that how do I maintain/publish changes to previous versions? My changes in /docs/** directory is not ready for publishing yet. So, what is the mechanism for maintaining changes to older version of docs?

Also, the documentation of Docusaurus says following:

Fallback Functionality

Only files in the docs directory and sidebar files that differ from those of the latest version will get copied each time a new version is specified. If there is no change across versions, Docusaurus will use the file from the latest version with that file.

For example, a document with the original id doc1 exists for the latest version, 1.0.0, and has the same content as the document with the id doc1 in the docs directory. When a new version 2.0.0 is created, the file for doc1 will not be copied into versioned_docs/version-2.0.0/. There will still be a page for docs/2.0.0/doc1.html, but it will use the file from version 1.0.0.

https://docusaurus.io/docs/en/versioning#fallback-functionality

So, let's say I now need to maintain/update a doc of a previous version but that file was not duplicated because at the time the new version was created, there wasn't any changes to this particular file. Now, what is the process? Do I manually copy the necessary file into /website/versioned-docs/version-${version-number} directory and then make my changes?

Yangshun Tay
  • 49,270
  • 33
  • 114
  • 141
aver
  • 555
  • 2
  • 7
  • 21
  • 1
    So, it seems the next version (V2) will address my concern about files not being saved if it didn't change from the previous version when new version is being created. https://docusaurus.io/blog/2018/09/11/Towards-Docusaurus-2 – aver Dec 28 '18 at 20:56

1 Answers1

0

Docusaurus maintainer here. Due to the way versioning is implemented, there's no easy way of updating previous versions in V1. You might not want to update previous versions as a version should be frozen when published and updates should be made to new versions.

But if you insist, you can always edit the generated files under the versioned_docs/version-X.X.X directories. However, I would recommend making changes to the latest version and encouraging your users to upgrade to the latest version.

Yangshun Tay
  • 49,270
  • 33
  • 114
  • 141
  • 1
    Thank you @yangshun for your reply. Yes, I also realize that we I can edit the files under `versioned_docs/version-X.X.X` directories. But, what if I needed to add new file under that version? What would be the yaml front matter original id field value? I don't think the documentation version should be frozen. Maybe the first time the documentation was not clear or need to provide additional docs that weren't available at the time. So, while source code for a particular version should be frozen, I think the related docs can always change. – aver Jan 11 '19 at 14:14