docusaurus-theme-docdive 0.3.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.
- package/README.md +17 -1
- package/package.json +2 -2
- 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
|
|
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.
|
|
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.
|
|
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
|
|
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
|
-
|
|
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,
|
|
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,
|
|
75
|
+
execFileSync(process.execPath, [docdiveCli, "build", docsDir, "--out", dest, "--root", repoRoot], { stdio: "inherit" });
|
|
67
76
|
writeMap(dest);
|
|
68
77
|
},
|
|
69
78
|
};
|