[Proposal] Docusarus NodeJS api

🚀 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.

https://github.com/facebook/docusaurus/blob/3548686f596bba8dcd79f57f6a697d8f06a2fcd3/packages/docusaurus/src/commands/start.ts#L215

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>
}>

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:

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

facebook / docusaurus