cudoc-docusaurus 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cudoment
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,31 @@
+# cudoc-docusaurus
+
+Connect cudoc to Docusaurus while retaining native heading IDs and TOC behavior.
+
+ESM · Node.js 20+
+
+```sh
+npm install @cudoment/cudoc cudoc-remark cudoc-docusaurus
+```
+
+```js
+import { cudocRemarkPlugins } from "cudoc-docusaurus"
+
+// In the Docusaurus docs plugin options:
+const docs = {
+  beforeDefaultRemarkPlugins: cudocRemarkPlugins({
+    syntax: { headingAnchor: "both", callout: "both" },
+  }),
+}
+```
+
+Use `markdown.format: "detect"` for `.md` and `.mdx`. Import `@cudoment/cudoc/styles.css` from site CSS. The explicit `syntax` setup needs no cudoc theme plugin or component registration. For embedding, use the actual Docusaurus compiler during collection and add `cudoc-remark/embed` afterward in the rendering pipeline.
+
+Choose `host`, `cudoc` or `both` independently for `headingAnchor`, `badge`, `tableCellList`, `callout` and `link`. The representative callout is `> [!NOTE] Title`. Authors do not register cudoc React components in the recommended setup. Syntax-only rendering needs no stored JSON; cross-document embedding requires document collection.
+
+- [Usage guide](https://github.com/cudoment/cudoc/tree/main/docs/docusaurus.md) · [한국어 가이드](https://github.com/cudoment/cudoc/tree/main/docs/docusaurus.ko.md)
+- [Markdown syntax](https://github.com/cudoment/cudoc/tree/main/docs/syntax.md)
+- [Embedding](https://github.com/cudoment/cudoc/tree/main/docs/embedding.md)
+- [Standalone HTML alongside a host](https://github.com/cudoment/cudoc/tree/main/docs/html.md#export-alongside-an-existing-site)
+- [API reference](https://github.com/cudoment/cudoc/tree/main/docs/api-reference/README.md)
+- [Runnable examples](https://github.com/cudoment/cudoc/tree/main/examples/README.md)

package/dist/heading-ids.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Copies the id from a cudoc anchor onto the heading itself.
+ *
+ * Docusaurus generates a heading id by slugifying the heading text, and builds
+ * its table of contents from those ids. Left alone it would produce a second id
+ * next to cudoc's anchor, and a deep link would resolve to whichever the
+ * browser found first. Its heading plugin honours an id that is already on
+ * `data.hProperties`, so writing the anchor id there makes the heading, the
+ * table of contents and the anchor agree on one value.
+ */
+import type { Root } from "mdast";
+import type { Plugin } from "unified";
+export type PromoteAnchorIdsOptions = {
+    /** Element name the id is read from. Matches `headingMetadata.anchor.name`. */
+    anchorName?: string;
+    /** Attribute the id is read from. Matches `headingMetadata.anchor.idAttribute`. */
+    idAttribute?: string;
+};
+export declare const promoteAnchorIds: Plugin<[PromoteAnchorIdsOptions?], Root>;
+export default promoteAnchorIds;
+//# sourceMappingURL=heading-ids.d.ts.map

package/dist/heading-ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heading-ids.d.ts","sourceRoot":"","sources":["../src/heading-ids.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAW,IAAI,EAAE,MAAM,OAAO,CAAA;AAC1C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAQrC,MAAM,MAAM,uBAAuB,GAAG;IACpC,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,mFAAmF;IACnF,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,CAAA;AAOD,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,CAAC,uBAAuB,CAAC,CAAC,EAAE,IAAI,CAoBrE,CAAA;AAED,eAAe,gBAAgB,CAAA"}

package/dist/heading-ids.js

@@ -0,0 +1,30 @@
+/**
+ * Copies the id from a cudoc anchor onto the heading itself.
+ *
+ * Docusaurus generates a heading id by slugifying the heading text, and builds
+ * its table of contents from those ids. Left alone it would produce a second id
+ * next to cudoc's anchor, and a deep link would resolve to whichever the
+ * browser found first. Its heading plugin honours an id that is already on
+ * `data.hProperties`, so writing the anchor id there makes the heading, the
+ * table of contents and the anchor agree on one value.
+ */
+import { visit } from "unist-util-visit";
+import { extractAnchorId, findAnchorNode, DEFAULT_ANCHOR_NAME, } from "cudoc-core";
+export const promoteAnchorIds = (options = {}) => {
+    const anchorName = options.anchorName ?? DEFAULT_ANCHOR_NAME;
+    const idAttribute = options.idAttribute ?? "id";
+    return (tree) => {
+        visit(tree, "heading", (heading) => {
+            const id = extractAnchorId(findAnchorNode(heading.children, anchorName), idAttribute);
+            if (!id)
+                return;
+            const data = (heading.data ?? (heading.data = {}));
+            const properties = data.hProperties ?? (data.hProperties = {});
+            // An id the author put there another way wins: this only fills a gap.
+            if (properties.id === undefined)
+                properties.id = id;
+        });
+    };
+};
+export default promoteAnchorIds;
+//# sourceMappingURL=heading-ids.js.map

package/dist/heading-ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"heading-ids.js","sourceRoot":"","sources":["../src/heading-ids.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AACxC,OAAO,EACL,eAAe,EACf,cAAc,EACd,mBAAmB,GACpB,MAAM,YAAY,CAAA;AAcnB,MAAM,CAAC,MAAM,gBAAgB,GAA6C,CACxE,OAAO,GAAG,EAAE,EACZ,EAAE;IACF,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,mBAAmB,CAAA;IAC5D,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,IAAI,CAAA;IAE/C,OAAO,CAAC,IAAU,EAAE,EAAE;QACpB,KAAK,CAAC,IAAI,EAAE,SAAS,EAAE,CAAC,OAAgB,EAAE,EAAE;YAC1C,MAAM,EAAE,GAAG,eAAe,CACxB,cAAc,CAAC,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,EAC5C,WAAW,CACZ,CAAA;YACD,IAAI,CAAC,EAAE;gBAAE,OAAM;YAEf,MAAM,IAAI,GAAG,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,GAAG,EAAE,CAAC,CAAgB,CAAA;YACjE,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,IAAI,CAAC,IAAI,CAAC,WAAW,GAAG,EAAE,CAAC,CAAA;YAC9D,sEAAsE;YACtE,IAAI,UAAU,CAAC,EAAE,KAAK,SAAS;gBAAE,UAAU,CAAC,EAAE,GAAG,EAAE,CAAA;QACrD,CAAC,CAAC,CAAA;IACJ,CAAC,CAAA;AACH,CAAC,CAAA;AAED,eAAe,gBAAgB,CAAA"}

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Docusaurus adapter.
+ *
+ * The anchors have to exist before Docusaurus assigns its own heading ids.
+ *
+ * The arrangement itself is `createHostPlugins`, shared with the Nextra
+ * adapter. What is specific to Docusaurus is the theme below, because this is
+ * the host where components are contributed by a plugin rather than named in a
+ * config file.
+ */
+import type { PluggableList } from "unified";
+import { type HostPluginOptions } from "cudoc-remark";
+export type CudocDocusaurusOptions = HostPluginOptions;
+/**
+ * The remark plugins to hand to `beforeDefaultRemarkPlugins`.
+ *
+ * They must run before Docusaurus assigns heading ids in its default plugins.
+ */
+export declare const cudocRemarkPlugins: (options?: CudocDocusaurusOptions) => PluggableList;
+type DocusaurusPlugin = {
+    name: string;
+    getThemePath: () => string;
+};
+/**
+ * The Docusaurus plugin, which contributes nothing but the theme components.
+ *
+ * cudoc emits capitalized elements, and MDX throws at render time when one is
+ * missing. Adding this plugin layers a `MDXComponents` over the site's own so
+ * the names resolve without anyone swizzling anything.
+ */
+declare const cudocDocusaurus: () => DocusaurusPlugin;
+export default cudocDocusaurus;
+export { promoteAnchorIds } from "cudoc-remark";
+export type { HostPluginOptions, PromoteAnchorIdsOptions } from "cudoc-remark";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAC5C,OAAO,EAAqB,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAExE,MAAM,MAAM,sBAAsB,GAAG,iBAAiB,CAAA;AAEtD;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAC7B,UAAS,sBAA2B,KACnC,aAA+D,CAAA;AAQlE,KAAK,gBAAgB,GAAG;IACtB,IAAI,EAAE,MAAM,CAAA;IACZ,YAAY,EAAE,MAAM,MAAM,CAAA;CAC3B,CAAA;AAED;;;;;;GAMG;AACH,QAAA,MAAM,eAAe,QAAO,gBAG1B,CAAA;AAEF,eAAe,eAAe,CAAA;AAC9B,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAC/C,YAAY,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA"}

package/dist/index.js

@@ -0,0 +1,34 @@
+/**
+ * Docusaurus adapter.
+ *
+ * The anchors have to exist before Docusaurus assigns its own heading ids.
+ *
+ * The arrangement itself is `createHostPlugins`, shared with the Nextra
+ * adapter. What is specific to Docusaurus is the theme below, because this is
+ * the host where components are contributed by a plugin rather than named in a
+ * config file.
+ */
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createHostPlugins } from "cudoc-remark";
+/**
+ * The remark plugins to hand to `beforeDefaultRemarkPlugins`.
+ *
+ * They must run before Docusaurus assigns heading ids in its default plugins.
+ */
+export const cudocRemarkPlugins = (options = {}) => createHostPlugins(options, "cudoc-docusaurus");
+const themePath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "theme");
+/**
+ * The Docusaurus plugin, which contributes nothing but the theme components.
+ *
+ * cudoc emits capitalized elements, and MDX throws at render time when one is
+ * missing. Adding this plugin layers a `MDXComponents` over the site's own so
+ * the names resolve without anyone swizzling anything.
+ */
+const cudocDocusaurus = () => ({
+    name: "cudoc-docusaurus",
+    getThemePath: () => themePath,
+});
+export default cudocDocusaurus;
+export { promoteAnchorIds } from "cudoc-remark";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAA;AAC5B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAExC,OAAO,EAAE,iBAAiB,EAA0B,MAAM,cAAc,CAAA;AAIxE;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAChC,UAAkC,EAAE,EACrB,EAAE,CAAC,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,CAAC,CAAA;AAElE,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAC5B,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAC5C,IAAI,EACJ,OAAO,CACR,CAAA;AAOD;;;;;;GAMG;AACH,MAAM,eAAe,GAAG,GAAqB,EAAE,CAAC,CAAC;IAC/C,IAAI,EAAE,kBAAkB;IACxB,YAAY,EAAE,GAAG,EAAE,CAAC,SAAS;CAC9B,CAAC,CAAA;AAEF,eAAe,eAAe,CAAA;AAC9B,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "cudoc-docusaurus",
+  "version": "0.2.0",
+  "description": "Docusaurus adapter for cudoc: remark wiring, default components and a theme that provides them.",
+  "keywords": [
+    "cudoc",
+    "docusaurus",
+    "docusaurus-plugin",
+    "mdx",
+    "documentation"
+  ],
+  "homepage": "https://github.com/cudoment/cudoc/tree/main/packages/cudoc-docusaurus#readme",
+  "bugs": {
+    "url": "https://github.com/cudoment/cudoc/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cudoment/cudoc.git",
+    "directory": "packages/cudoc-docusaurus"
+  },
+  "license": "MIT",
+  "author": "cudoment",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "theme",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "dependencies": {
+    "cudoc-remark": "0.2.0",
+    "unified": "^11.0.5"
+  },
+  "peerDependencies": {
+    "@docusaurus/core": "^3.0.0",
+    "react": "^18.0.0 || ^19.0.0"
+  }
+}

package/theme/MDXComponents/index.jsx

@@ -0,0 +1,22 @@
+/**
+ * Layers cudoc's components over the ones the site theme already provides.
+ *
+ * `@theme-init` rather than `@theme-original`: Docusaurus points
+ * `@theme-original/X` at the topmost theme that provides `X`, which for a
+ * component contributed by a plugin is this file itself. `@theme-init/X` is the
+ * theme that first provided it — the classic theme here — so this is the alias
+ * a plugin has to use to wrap a component instead of replacing it.
+ *
+ * The implementations come from `cudoc-remark`, so all three supported hosts
+ * render the same markup. They arrive compiled, which matters here: Docusaurus
+ * does not transpile JSX inside `node_modules` unless the path contains
+ * "docusaurus".
+ */
+
+import MDXComponents from "@theme-init/MDXComponents"
+import { cudocComponents } from "cudoc-remark/components"
+
+export default {
+  ...MDXComponents,
+  ...cudocComponents,
+}