Config option for not including next release docs in the final build

[amimas]

🚀 Feature

Provide a build option or a configuration so that we can choose whether or not to include the docs for the next release, when it's being built.

Have you read the Contributing Guidelines on issues?

Yes

Motivation

Being able to publish different versions of docs easily is a great feature. Existing setup also means that when you build the site, you'll have docs for all of the different version of the product and the next release, which is currently under development. This may be perfect for open source projects. For example, the docs for next release of docusaurus is available here:

https://docusaurus.io/docs/en/next/installation

Others may not want to have documentation released yet for a version that has not been officially published. But in the meantime, if you need to make corrections/update to docs for existing version and publish, there's no way of separating or omitting the publishing of docs for next release.

Pitch

(Please explain why this feature should be implemented and how it would be used.)

This feature would allow much more flexibility to the end user. They don't have to come up with work-arounds or hacks just to make sure that the docs for the release that is currently being developed is not being published while still able to maintain changes to previous release docs.

[parthpp]

@yangshun @endiliey @JoelMarcey What are your thoughts on this feature. We really need this for our project and I am interested in implementing this feature. As far as I can understand from the code base, I need to look into generate.js. Do you have any pointers/suggestion on where should I do a deep dive in the codebase?

[JoelMarcey]

I am not adverse to implementing this -- it could possibly be a build option if we do it in v1. https://docusaurus.io/docs/en/command ?

[amimas]

I agree. Using a "build option" is probably a better approach. Something like --skip-next-release-docs

[endiliey]

I am not against this and will be happy to see this, but I think there are quite lot of places/ code that need to be changed to achieve this.

I personally feel creating your own script to remove the next folder from the website/build is much easier IMO. Just few lines of code to achieve the same thing 😄

[yangshun]

I personally feel creating your own script to remove the next folder from the website/build is much easier IMO.

It definitely is, but links on the "All Versions" page might be broken :/

[amimas]

I personally feel creating your own script to remove the next folder from the website/build is much easier IMO.

Yes, that can be done too and I have thought about it as well. Personally it just felt more like a work-around.

This feature request can be useful to others too. That's why I raised it here and if you agree, my friend @parthpp can help contribute. We just need a bit guidance as neither of has experience with Docusaurus' code base.

[parthpp]

@yangshun @endiliey @JoelMarcey

I would like to propose the following design changes to implement this feature.
The build command yarn run build --skip-next-docs will build the static
website but will skip the current version of documents in docs or siteconfig.customDocsPath.
Thus on deployment of such a website there is no path of type **/next**. If
the website does not use versioning, then this option will have no effect.

One of the ways we can do this is by not generating the metadata for the markdown files
under docs or siteconfig.customDocsPath when versioning is enabled and yarn run build --skip-next-docs is executed. Thus, when versioning is enabled and this option is used, we generate metadata using only the documents under versioned_docs. Since, the html generation code relies on metadata.js, which in this case would not have the metadata for next, it will not build html files for these documents.

An appropriate place to make these changes would be readMetaData.generateMetadataDocs.
readMetadata.generateMetadataDocs(boolean isNextMetadataRequired) will go ahead with logic from
L223,290 based on the value of isNextMetadataRequired and env.versioning.enabled.

Let me know your thought on this approach.

Thanks

[amimas]

One of the ways we can do this is by not generating the metadata for the markdown files
under docs or siteconfig.customDocsPath when versioning is enabled.

You mean, that will happen only if the build command (--skip-next-docs) is used, right? I think we need to keep it as flexible as possible. Some use cases (i.e. open source projects) may want to include the next release docs when they build it.

[parthpp]

One of the ways we can do this is by not generating the metadata for the markdown files
under docs or siteconfig.customDocsPath when versioning is enabled.

You mean, that will happen only if the build command (--skip-next-docs) is used, right? I think we need to keep it as flexible as possible. Some use cases (i.e. open source projects) may want to include the next release docs when they build it.

Yes, it will only happen when the --skip-next-docs option is used. I have updated the comment to be more specific.

[endiliey]

Your approach looks OK for me. Feel free to send a PR asap if you want it to ship within next release. This isn't a high priority though

[parthpp]

@endiliey build-files.test.js uses the actual Docusaurus documentation to perform testing. I am just curious to know why we did not use a separate test data for this test?