Support Partial Build

[heywalter]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Motivation

For example, we have enabled the multi-doc instances plugin. If we only update the documentation in one instance, we want to build and publish only that instance document, not all instance documentation.
This feature can help minimize the build time in large projects.

Self-service

• I'd be willing to do some initial work on this proposal myself.

[slorber]

What you ask here is quite complicated to build, because in the end the Docusaurus app must be one single-page application.

We should be able to transition from a doc to a blog post with an SPA soft navigation, which means the SPA router routes should be shared between all the plugin instances that you want to build. This also means we probably need a command to build the "shell/container" that will be able to receive and plug the host application slices (plugin instances).

And when redeploying one plugin instance routes, it shouldn't break the code that already exists and is deployed.

Webpakc Module Federation can probably support that, however, it's not a simple subject: https://webpack.js.org/concepts/module-federation/

Of course there are other problems to consider like how we generate global things in postBuild like the sitemap.xml, referencing all the urls of a given site. We should then update

Also, it would be hard to detect broken links across plugin instances that have not be built.

---

It's not clear to me how you see yourself hosting this in practice, can you describe this more precisely?

• What is your site url (or urls if many)
• Where is this hosted? Self-hosted? CDN?
• What CI commands do you run to host it the first time
• What CI commands do run to redeploy a plugin instance
• How is your sitemap updated on redeploy?

---

Really, this looks complicated to me and the source of many problems. I'd rather spend time optimizing the build rather than implementing this, if the goal is only to deploy faster.

Note that another solution would be to "shard" your site, and actually split it into multiple smaller Docusaurus sites. You don't need to have 2 Docusaurus site folders for that, and can use env variables in a single config file to build your docs and your blog as separate standalone sites.

INSTANCE=docs docusaurus build
INSTANCE=blog docusaurus build

Note we already do that for i18n: each locale is a standalone site, and you can deploy each localized site independently, using multiple strategies (all locales on same domain or one subdomain per locale). The same can be applied to docs/blog:

https://docusaurus.io/docs/i18n/tutorial#deploy-your-site

[heywalter]

Our current product documentation is maintained locally, covering nearly 20 products, each with its own version. In total, there are around 10,000 Markdown files, and the HTML files generated by scripts amount to nearly 8GB.

We plan to use Docusaurus for managing and publishing our external product documentation. We haven't started the actual deployment and migration yet, so there are no URLs or CI configuration details to share at the moment. We anticipate adopting a self-hosted approach.

Our current idea is to centralize the documentation of all products on one site for publication, but this raises concerns about update performance. I'm unsure about the build performance of Docusaurus, hence my concern upon seeing related issues here.

I wonder if there's a more efficient way to manage documentation in this scenario? Thanks.

[slorber]

Docusaurus is not the fastest SSG tool out there, and is slower than some alternatives in Rust or Go, but the experience for the end user is also IMHO better because it's an SPA that has a fluid soft navigation experience, preserving UI state when navigation. This kind of experience is more costly to build in general because we are building an SPA app, not just individual standalone HTML pages.

Now if you have 20 products, why not splitting your docs in 20 smaller sites?
It does not mean that the 20 sites should be independently coded: you can share most of the config, theme, CSS and everything, so that technically all the 20 sites kind of look the same, and it's possible to link from one site to another quite easily.

Take this as an example:

• https://www.figma.com/plugin-docs/
• https://www.figma.com/widget-docs/

Those 2 are distinct Docusaurus sites sharing the same navbar/footer/layout/UI/CSS/infrastructure.

You can see that because when navigating from plugin to widget, it's a real browser navigation and not an SPA soft navigation.

This enables Figma to be able to deploy just the plugin site without redeploying the widget site.

[heywalter]

This seems like a great idea, thank you. Could I ask for the specific implementation steps? For example, how to maintain a consistent navigation bar after splitting, and how to configure the docusaurus.config.js. Thank you.

[slorber]

@heywalter you could simply have one config file for both sites, and use env variables to toggle respective plugins.

MODE=blog docusaurus build
MODE=docs docusaurus build

const mode = process.env.MODE;

// Note you can also keep things on the same domain, and use different baseUrls for each plugin
const url = mode === "docs" ? "https://docs.myDomain.com" : "https://blog.myDomain.com"

const presetConfig = {
  docs: mode === "docs" ? yourDocsOptions : false,
  blog: mode === "blog" ? yourBlogOptions : false,
}

For more complex cases, and avoiding a single messy config file, you could also use different config files:

docusaurus build --config docusaurus.blog.config.js
docusaurus build --config docusaurus.docs.config.js

And you can put shared Docusaurus config in a docusaurus.shared.config.js.

For example if you want a consistent navbar, you can put the themeConfig.navbar in that shared config file

[heywalter]

Got it, thanks for your help.

[slorber]

Great that you find it helpful.

I'm going to close this issue because "partial build" is kind of abstract to me.

But if someone can define precisely what it is and how this should be implemented, I'll remain open to the discussion and we'll eventually reopen.

Thanks