docusaurus-theme-docdive 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -19,4 +19,11 @@ module.exports = {
19
19
  Remove the theme line and the site falls back to the native Mermaid component. The docs folder is taken from the docs
20
20
  plugin. Optional theme option: `src` (repo root that `src:` frontmatter paths are relative to, relative to the site dir).
21
21
 
22
+ ## Dev mode
23
+
24
+ `docusaurus start` works with no extra config. The theme runs `docdive watch` on the docs folder, writes its output to
25
+ `.docusaurus/docdive/` and serves it at `<baseUrl>docdive/`. Diagrams are interactive right away. After you edit a
26
+ Markdown file, reload the page to see the new data (no auto-reload). A build error in the docs is logged and the last
27
+ good data is kept. `docusaurus build` is unchanged.
28
+
22
29
  Peers: `@docusaurus/core` and `@docusaurus/theme-mermaid` ^3.10, `mermaid` >=11.6 <13. Requires Node >= 22.12. MIT.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "docusaurus-theme-docdive",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "Docusaurus theme that renders Mermaid fences as interactive docdive diagrams.",
5
5
  "license": "MIT",
6
6
  "author": "Thibaud Navarre",
@@ -25,7 +25,7 @@
25
25
  "node": ">=22.12"
26
26
  },
27
27
  "dependencies": {
28
- "docdive": "^0.1.0"
28
+ "docdive": "^0.2.0"
29
29
  },
30
30
  "peerDependencies": {
31
31
  "@docusaurus/core": "^3.10.0",
package/src/index.cjs CHANGED
@@ -1,10 +1,12 @@
1
1
  // CommonJS on purpose: Docusaurus loads theme modules through jiti, which cannot evaluate `import.meta`.
2
- const { execFileSync } = require("node:child_process");
2
+ const { execFileSync, spawn } = require("node:child_process");
3
3
  const { mkdirSync, writeFileSync } = require("node:fs");
4
4
  const { dirname, join, relative, resolve, sep } = require("node:path");
5
5
 
6
6
  const docdiveCli = join(dirname(require.resolve("docdive/package.json")), "dist", "cli.js");
7
7
 
8
+ let watcherStarted = false;
9
+
8
10
  /**
9
11
  * docdive adapter for Docusaurus. A theme (not a plain plugin), listed after @docusaurus/theme-mermaid so its
10
12
  * Mermaid component wraps @theme-init/Mermaid. Data only: the product logic lives in the `docdive` CLI.
@@ -14,6 +16,12 @@ const docdiveCli = join(dirname(require.resolve("docdive/package.json")), "dist"
14
16
  module.exports = function docdiveTheme(context, options = {}) {
15
17
  let docsDir;
16
18
  let docMap = {};
19
+ const devDir = join(context.generatedFilesDir, "docdive");
20
+ const srcArgs = () => (options.src ? ["--src", resolve(context.siteDir, options.src)] : []);
21
+ const writeMap = (dir) => {
22
+ mkdirSync(dir, { recursive: true });
23
+ writeFileSync(join(dir, "docdive-map.json"), JSON.stringify(docMap, null, 2) + "\n");
24
+ };
17
25
 
18
26
  return {
19
27
  name: "docusaurus-theme-docdive",
@@ -29,16 +37,34 @@ module.exports = function docdiveTheme(context, options = {}) {
29
37
  const abs = resolve(context.siteDir, doc.source.replace(/^@site\//, ""));
30
38
  docMap[relative(docsDir, abs).split(sep).join("/")] = doc.permalink;
31
39
  }
40
+ // Re-runs on every docs reload under `docusaurus start`, which keeps the dev map fresh.
41
+ writeMap(devDir);
42
+ },
43
+
44
+ // `devServer` is only read by webpack-dev-server, so `docusaurus build` is unaffected.
45
+ configureWebpack(_config, isServer) {
46
+ if (isServer) return {};
47
+ return {
48
+ devServer: {
49
+ static: [{ directory: devDir, publicPath: `${context.baseUrl}docdive`, watch: false }],
50
+ // onListening is only called by webpack-dev-server. Never define setupMiddlewares here: Docusaurus does.
51
+ onListening() {
52
+ if (watcherStarted || !docsDir) return;
53
+ watcherStarted = true;
54
+ const child = spawn(process.execPath, [docdiveCli, "watch", docsDir, "--out", devDir, ...srcArgs()], {
55
+ stdio: "inherit",
56
+ });
57
+ process.on("exit", () => child.kill());
58
+ },
59
+ },
60
+ };
32
61
  },
33
62
 
34
63
  async postBuild({ outDir }) {
35
64
  if (!docsDir) throw new Error("docusaurus-theme-docdive: the docs plugin has no content to index");
36
65
  const dest = join(outDir, "docdive");
37
- const args = [docdiveCli, "build", docsDir, "--out", dest];
38
- if (options.src) args.push("--src", resolve(context.siteDir, options.src));
39
- execFileSync(process.execPath, args, { stdio: "inherit" });
40
- mkdirSync(dest, { recursive: true });
41
- writeFileSync(join(dest, "docdive-map.json"), JSON.stringify(docMap, null, 2) + "\n");
66
+ execFileSync(process.execPath, [docdiveCli, "build", docsDir, "--out", dest, ...srcArgs()], { stdio: "inherit" });
67
+ writeMap(dest);
42
68
  },
43
69
  };
44
70
  };