docusaurus-theme-docdive 0.2.0 → 0.4.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.
Files changed (3) hide show
  1. package/README.md +17 -1
  2. package/package.json +2 -2
  3. package/src/index.cjs +14 -5
package/README.md CHANGED
@@ -17,7 +17,20 @@ module.exports = {
17
17
  ```
18
18
 
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
- plugin. Optional theme option: `src` (repo root that `src:` frontmatter paths are relative to, relative to the site dir).
20
+ plugin. Optional theme option `sourceUrl`: template for the panel's Source link, with `{path}` (doc path relative to
21
+ the docs dir) and `{line}`, e.g. `https://git.example.com/org/repo/src/main/docs/{path}#L{line}`. Wins over `editUrl`.
22
+
23
+ ## Source link
24
+
25
+ Selecting a node can show a **Source** link that opens the repo page at the Markdown line where the node is declared
26
+ (or first mentioned). The URL comes from the docs plugin's `editUrl`: a GitHub `/edit/` or GitLab `/-/edit/` URL is
27
+ rewritten to its `/blob/` view with `#L<line>`. Other hosts need `sourceUrl`. With neither, the link is hidden.
28
+
29
+ The same edit URL turns the panel's `src` paths and the state entities declared with `entities:` into links to the
30
+ repo (`https://github.com/org/repo/blob/main/<path>`). Other hosts, or a branch name containing `/`, need the theme
31
+ option `srcUrl`: a template with `{path}` (repo-root-relative), e.g. `https://git.example.com/org/repo/src/main/{path}`.
32
+ Files that exist under the repo root (theme option `root`, relative to the site dir, default `.`) are copied into
33
+ `<site>/docdive/src/` and a plain click shows them in the page; ⌘/ctrl-click still opens the repo. Directories only link.
21
34
 
22
35
  ## Dev mode
23
36
 
@@ -27,3 +40,6 @@ Markdown file, reload the page to see the new data (no auto-reload). A build err
27
40
  good data is kept. `docusaurus build` is unchanged.
28
41
 
29
42
  Peers: `@docusaurus/core` and `@docusaurus/theme-mermaid` ^3.10, `mermaid` >=11.6 <13. Requires Node >= 22.12. MIT.
43
+
44
+ Overview page: write `<docdive-map></docdive-map>` in any Markdown page to show the element tree and the flows, each
45
+ linking to its page. The element script is loaded on every page, so no extra setup is needed.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "docusaurus-theme-docdive",
3
- "version": "0.2.0",
3
+ "version": "0.4.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.2.0"
28
+ "docdive": "^0.4.0"
29
29
  },
30
30
  "peerDependencies": {
31
31
  "@docusaurus/core": "^3.10.0",
package/src/index.cjs CHANGED
@@ -11,13 +11,16 @@ let watcherStarted = false;
11
11
  * docdive adapter for Docusaurus. A theme (not a plain plugin), listed after @docusaurus/theme-mermaid so its
12
12
  * Mermaid component wraps @theme-init/Mermaid. Data only: the product logic lives in the `docdive` CLI.
13
13
  *
14
- * Options: `src` (repo root for `src:` frontmatter paths, relative to the site dir; optional).
14
+ * Options (both optional, both win over the docs `editUrl`): `sourceUrl`, click-to-source template with `{path}` =
15
+ * doc path relative to the docs dir and `{line}`; `srcUrl`, template with `{path}` = repo-root-relative path, for
16
+ * the `src:` / `entities:` links. `root`: repo root the `src:` / `entities:` paths resolve against, so their files are
17
+ * copied into the site and shown inline (default: the site dir).
15
18
  */
16
19
  module.exports = function docdiveTheme(context, options = {}) {
20
+ const repoRoot = resolve(context.siteDir, options.root ?? ".");
17
21
  let docsDir;
18
22
  let docMap = {};
19
23
  const devDir = join(context.generatedFilesDir, "docdive");
20
- const srcArgs = () => (options.src ? ["--src", resolve(context.siteDir, options.src)] : []);
21
24
  const writeMap = (dir) => {
22
25
  mkdirSync(dir, { recursive: true });
23
26
  writeFileSync(join(dir, "docdive-map.json"), JSON.stringify(docMap, null, 2) + "\n");
@@ -33,10 +36,16 @@ module.exports = function docdiveTheme(context, options = {}) {
33
36
  const version = allContent["docusaurus-plugin-content-docs"]?.default?.loadedVersions?.[0];
34
37
  docsDir = version?.contentPath;
35
38
  docMap = {};
39
+ const sources = {};
36
40
  for (const doc of version?.docs ?? []) {
37
41
  const abs = resolve(context.siteDir, doc.source.replace(/^@site\//, ""));
38
- docMap[relative(docsDir, abs).split(sep).join("/")] = doc.permalink;
42
+ const key = relative(docsDir, abs).split(sep).join("/");
43
+ docMap[key] = doc.permalink;
44
+ if (doc.editUrl) sources[key] = doc.editUrl;
39
45
  }
46
+ if (Object.keys(sources).length) docMap.sources = sources;
47
+ if (options.sourceUrl) docMap.sourceUrl = options.sourceUrl;
48
+ if (options.srcUrl) docMap.srcUrl = options.srcUrl;
40
49
  // Re-runs on every docs reload under `docusaurus start`, which keeps the dev map fresh.
41
50
  writeMap(devDir);
42
51
  },
@@ -51,7 +60,7 @@ module.exports = function docdiveTheme(context, options = {}) {
51
60
  onListening() {
52
61
  if (watcherStarted || !docsDir) return;
53
62
  watcherStarted = true;
54
- const child = spawn(process.execPath, [docdiveCli, "watch", docsDir, "--out", devDir, ...srcArgs()], {
63
+ const child = spawn(process.execPath, [docdiveCli, "watch", docsDir, "--out", devDir, "--root", repoRoot], {
55
64
  stdio: "inherit",
56
65
  });
57
66
  process.on("exit", () => child.kill());
@@ -63,7 +72,7 @@ module.exports = function docdiveTheme(context, options = {}) {
63
72
  async postBuild({ outDir }) {
64
73
  if (!docsDir) throw new Error("docusaurus-theme-docdive: the docs plugin has no content to index");
65
74
  const dest = join(outDir, "docdive");
66
- execFileSync(process.execPath, [docdiveCli, "build", docsDir, "--out", dest, ...srcArgs()], { stdio: "inherit" });
75
+ execFileSync(process.execPath, [docdiveCli, "build", docsDir, "--out", dest, "--root", repoRoot], { stdio: "inherit" });
67
76
  writeMap(dest);
68
77
  },
69
78
  };