[Proposal] Docusarus NodeJS api

[fforres]

🚀 Feature

Expose (some) docusaurus functionality through a NodeJS api.

Have you read the Contributing Guidelines on issues?

Yes

Motivation

At my work I have implemented an automated documentation flow using docusaurus, react-docgen, react-docgen-typescript and file-watchers.

We are aiming maintain a good DX in writing documents, so we implemented a flow that uses chokidar to watch multiple project's files (Files in our component library repository, our mobile repo, our main application repo, etc) and generate a bunch of .md files that then docusuarus renders.

However, there is ATM not an "official" way to programmatically start/stop a docusaurus process.

Pitch

ATM our solution is to reach inside docusaurus core

import { start as startDocusaurus } from "@docusaurus/core/lib";


/// much code

startDocusaurus(DOCS_ROOT, {
    port: undefined,
    host: undefined,
    locale: undefined,
    hotOnly: undefined,
    open: true,
    poll: undefined,
});

Unsure on the API exactly, but Ideally we would expose a method that would essentially return a a wrapper around WebpackDevServer 's .listen and .close methods, so expose specific controls over it and not return the whole devServer.

docusaurus/packages/docusaurus/src/commands/start.ts

Line 215 in 3548686

const devServer = new WebpackDevServer(compiler, devServerConfig);

A rough schema of what I have in mind

type SomeDocusaurusInformation = {
	pid: number;
	port: number;
	filesWatched: string[];
	/// idk, something else. 
}

export default async function start(
  siteDir: string,
  cliOptions: Partial<StartCLIOptions>,
): Promise<{
	start: Promise<SomeDocusaurusInformation>
	close: Promise<void>
}> 

[slorber]

At my work I have implemented an automated documentation flow using docusaurus, react-docgen, react-docgen-typescript and file-watchers.

You could implement a plugin, the getPathsToWatch lifecycle allows to register a path like somePath/**/*.md and content will hot reload everytime a file changes

I'd also like to make it easier to integrate with CMSs. The issue is a bit messy but you may find relevant intos here:

• Extend existing content plugins (CMS integration, middleware, doc gen...) #4138
• Proposal: enable option to propagate arbitrary frontmatter data in globals #4492

We could have a way for plugins to trigger site content reloads on a per-plugin basis, eventually, listen for a CMS to send a notification for changes etc...

I don't think we'll expose an imperative Nodejs API, but rather expose the required APIs for such use-cases through plugin lifecycles. You will have to implement your own plugin