facebook / facebook/docusaurus

[Proposal] Docusarus NodeJS api

Ouverte
#4,841 1 commentaire 0 réactions 0 personnes assignées Voir sur GitHub
proposal
Langage dominant
TypeScript
Étoiles
66.2k
Forks
10k
Merge moyen
1 j 3 h
PR mergées (30 j)
52

Description

## 🚀 Feature

Expose (some) docusaurus functionality through a NodeJS api.

### Have you read the [Contributing Guidelines on issues](https://github.com/facebook/docusaurus/blob/master/CONTRIBUTING.md#reporting-new-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

```TSX
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
```TSX

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

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

```

Guide de contribution

Ouvrir le guide de contribution

Évaluation

Cette issue n'a pas encore été évaluée.

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.