facebook / facebook/docusaurus

[Proposal] Docusarus NodeJS api

Abierto
#4,841 1 comentario 0 reacciones 0 asignados Ver en GitHub
proposal
Lenguaje dominante
TypeScript
Estrellas
66.2k
Forks
10k
Merge medio
1 d 3 h
PR fusionados (30 d)
52

Descripción

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

```

Guía de contribución

Abrir la guía de contribución

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.