@graphql-markdown/docusaurus 1.28.0 → 1.29.1

package/README.md

@@ -3,10 +3,8 @@
 [![Latest Version](https://img.shields.io/npm/v/@graphql-markdown/docusaurus?style=flat)](https://www.npmjs.com/package/@graphql-markdown/docusaurus)
 [![GitHub License](https://img.shields.io/github/license/graphql-markdown/graphql-markdown?style=flat)](https://raw.githubusercontent.com/graphql-markdown/graphql-markdown/main/LICENSE)
 [![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=graphql-markdown_docusaurus&metric=sqale_index)](https://sonarcloud.io/summary/new_code?id=graphql-markdown_docusaurus)
-<!--
 [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=graphql-markdown_docusaurus&metric=coverage)](https://sonarcloud.io/summary/new_code?id=graphql-markdown_docusaurus)
-[![Mutation Score](https://img.shields.io/endpoint?label=mutation%20score&style=flat&url=https%3A%2F%2Fbadge-api.stryker-mutator.io%2Fgithub.com%2Fgraphql-markdown%2Fgraphql-markdown%2Fmain%3Fmodule%3Ddocusarus)](https://dashboard.stryker-mutator.io/reports/github.com/graphql-markdown/graphql-markdown/main?module=docusarus)
--->
+[![Mutation Score](https://img.shields.io/endpoint?label=mutation%20score&style=flat&url=https%3A%2F%2Fbadge-api.stryker-mutator.io%2Fgithub.com%2Fgraphql-markdown%2Fgraphql-markdown%2Fmain%3Fmodule%3Ddocusaurus)](https://dashboard.stryker-mutator.io/reports/github.com/graphql-markdown/graphql-markdown/main?module=docusaurus)
 
 **Docusaurus** [docs feature](https://docusaurus.io/docs/docs-introduction) plugin for generating **Markdown documentation** from a **GraphQL schema**.
 
@@ -16,7 +14,7 @@
 npm init docusaurus my-website https://github.com/graphql-markdown/template.git
 ```
 
-> _If you already have an existing Docusaurus installation, then see the [documentation](https://graphql-markdown.dev/docs/get-started) for alternative installation._
+> _If you already have an existing Docusaurus installation, then see the [documentation](https://graphql-markdown.dev/docs/get-started/#existing-docusaurus-site) for an alternative installation._
 
 ## Usage
 
@@ -40,4 +38,4 @@ See [documentation troubleshooting](https://graphql-markdown.dev/docs/troublesho
 
 GraphQL-Markdown packages are 100% free and open-source, under the [MIT license](https://github.com/graphql-markdown/graphql-markdown/blob/main/LICENSE).
 
-This package is [Treeware](https://treeware.earth). If you use it in production, then we ask that you [**buy the world a tree**](https://plant.treeware.earth/graphql-markdown/graphql-markdown) to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.
+This package is [Treeware](https://treeware.earth). If you use it in production, then we ask that you [**buy the world a tree**](https://plant.treeware.earth/graphql-markdown/graphql-markdown) to thank us for our work. By contributing to the Treeware forest, you’ll be creating employment for local families and restoring wildlife habitats.

package/dist/index.d.ts

@@ -1,3 +1,6 @@
 import type { LoadContext, Plugin, PluginOptions } from "@docusaurus/types";
 import type { GraphQLMarkdownCliOptions } from "@graphql-markdown/types";
+/**
+ *
+ */
 export default function pluginGraphQLDocGenerator(_: LoadContext, options: GraphQLMarkdownCliOptions & Partial<PluginOptions>): Promise<Plugin>;

package/dist/index.js

@@ -10,16 +10,30 @@ const logger_1 = __importDefault(require("@graphql-markdown/logger"));
 const NAME = "docusaurus-graphql-doc-generator";
 const LOGGER_MODULE = "@docusaurus/logger";
 const MDX_PACKAGE = "@graphql-markdown/docusaurus/mdx";
+/**
+ *
+ */
 async function pluginGraphQLDocGenerator(_, options) {
     await (0, logger_1.default)(LOGGER_MODULE);
     return {
         name: NAME,
+        /**
+         * @experimental
+         */
         async loadContent() {
             if (options.runOnBuild !== true) {
                 return;
             }
             await (0, cli_1.runGraphQLMarkdown)(options, {}, LOGGER_MODULE);
         },
+        /**
+         * Extends Docusaurus CLI with GraphQL Documentation generator command.
+         * This method adds a custom command to generate GraphQL documentation
+         * using the configured options.
+         *
+         * @param cli - The Docusaurus CLI instance to extend
+         * @returns void
+         */
         extendCli(cli) {
             cli.addCommand((0, cli_1.getGraphQLMarkdownCli)({
                 ...options,

package/dist/mdx/category.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @module mdx
+ * This module provides utilities for generating MDX index files in Docusaurus format.
+ */
+import type { GenerateIndexMetafileType } from "@graphql-markdown/types";
+export declare const generateIndexMetafile: GenerateIndexMetafileType;

package/dist/mdx/category.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * @module mdx
+ * This module provides utilities for generating MDX index files in Docusaurus format.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateIndexMetafile = void 0;
+const node_path_1 = require("node:path");
+const utils_1 = require("@graphql-markdown/utils");
+const CATEGORY_YAML = "_category_.yml";
+var SidebarPosition;
+(function (SidebarPosition) {
+    SidebarPosition[SidebarPosition["FIRST"] = 1] = "FIRST";
+    SidebarPosition[SidebarPosition["LAST"] = 999] = "LAST";
+})(SidebarPosition || (SidebarPosition = {}));
+const generateIndexMetafile = async (dirPath, category, options) => {
+    const filePath = (0, node_path_1.join)(dirPath, CATEGORY_YAML);
+    if (await (0, utils_1.fileExists)(filePath)) {
+        return;
+    }
+    const label = (0, utils_1.startCase)(category);
+    const link = options?.index !== true
+        ? "null"
+        : `\n  type: generated-index\n  title: '${label} overview'`;
+    const className = typeof options?.styleClass === "string"
+        ? `className: ${options.styleClass}\n`
+        : "";
+    const position = typeof options?.sidebarPosition === "number"
+        ? options.sidebarPosition
+        : SidebarPosition.FIRST;
+    const content = `label: ${label}\nposition: ${position}\n${className}link: ${link}\ncollapsible: ${options?.collapsible ?? true}\ncollapsed: ${options?.collapsed ?? true}\n`;
+    await (0, utils_1.ensureDir)(dirPath);
+    await (0, utils_1.saveFile)(filePath, content);
+};
+exports.generateIndexMetafile = generateIndexMetafile;

package/dist/mdx/components.d.ts

@@ -1,2 +1,6 @@
+/**
+ * @module mdx
+ * This module provides MDX React components.
+ */
 import type { MDXString } from "@graphql-markdown/types";
 export declare const mdxDeclaration: MDXString;

package/dist/mdx/components.js

@@ -1,4 +1,8 @@
 "use strict";
+/**
+ * @module mdx
+ * This module provides MDX React components.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.mdxDeclaration = void 0;
 exports.mdxDeclaration = `

package/dist/mdx/index.d.ts

@@ -1,12 +1,45 @@
-import type { AdmonitionType, Badge, Maybe, MDXString, MetaOptions, TypeLink } from "@graphql-markdown/types";
+/**
+ * @module mdx
+ * This module provides utilities for generating MDX content in Docusaurus format.
+ * It includes functions for creating badges, admonitions, bullet points, collapsible sections,
+ * specification links, and other MDX-specific formatting for GraphQL documentation.
+ *
+ * @primaryExport
+ */
+import type { AdmonitionType, Badge, CollapsibleOption, Maybe, MDXString, MetaOptions, TypeLink } from "@graphql-markdown/types";
 export { mdxDeclaration } from "./components";
+export { generateIndexMetafile } from "./category";
 export declare const formatMDXBadge: ({ text, classname }: Badge) => MDXString;
+/**
+ * Formats an admonition block in MDX format
+ * @param param - The admonition configuration object
+ * @param meta - Optional metadata for generator configuration
+ * @returns Formatted MDX string for the admonition
+ */
 export declare const formatMDXAdmonition: ({ text, title, type }: AdmonitionType, meta: Maybe<MetaOptions>) => MDXString;
+/**
+ * Creates a bullet point element in MDX format
+ * @param text - Optional text to append after the bullet point
+ * @returns Formatted MDX string for the bullet point
+ */
 export declare const formatMDXBullet: (text?: string) => MDXString;
-export declare const formatMDXDetails: ({ dataOpen, dataClose, }: {
-    dataOpen: Maybe<string>;
-    dataClose: Maybe<string>;
-}) => MDXString;
+/**
+ * Creates a collapsible details section in MDX format
+ * @param param - The collapsible section configuration
+ * @returns Formatted MDX string for the collapsible section
+ */
+export declare const formatMDXDetails: ({ dataOpen, dataClose, }: CollapsibleOption) => MDXString;
+/**
+ * Creates a link to the specification documentation
+ * @param url - The URL to the specification
+ * @returns Formatted MDX string for the specification link
+ */
 export declare const formatMDXSpecifiedByLink: (url: string) => MDXString;
+/**
+ * Formats a name entity with optional parent type
+ * @param name - The name to format
+ * @param parentType - Optional parent type to prefix the name
+ * @returns Formatted MDX string for the name entity
+ */
 export declare const formatMDXNameEntity: (name: string, parentType?: Maybe<string>) => MDXString;
 export declare const formatMDXLink: ({ text, url }: TypeLink) => TypeLink;

package/dist/mdx/index.js

@@ -1,15 +1,34 @@
 "use strict";
+/**
+ * @module mdx
+ * This module provides utilities for generating MDX content in Docusaurus format.
+ * It includes functions for creating badges, admonitions, bullet points, collapsible sections,
+ * specification links, and other MDX-specific formatting for GraphQL documentation.
+ *
+ * @primaryExport
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.formatMDXLink = exports.formatMDXNameEntity = exports.formatMDXSpecifiedByLink = exports.formatMDXDetails = exports.formatMDXBullet = exports.formatMDXAdmonition = exports.formatMDXBadge = exports.mdxDeclaration = void 0;
+exports.formatMDXLink = exports.formatMDXNameEntity = exports.formatMDXSpecifiedByLink = exports.formatMDXDetails = exports.formatMDXBullet = exports.formatMDXAdmonition = exports.formatMDXBadge = exports.generateIndexMetafile = exports.mdxDeclaration = void 0;
+const utils_1 = require("@graphql-markdown/utils");
 const MARKDOWN_EOL = "\n";
 const MARKDOWN_EOP = `${MARKDOWN_EOL.repeat(2)}`;
 const LINK_MDX_EXTENSION = ".mdx";
+const DEFAULT_CSS_CLASSNAME = "badge--secondary";
 var components_1 = require("./components");
 Object.defineProperty(exports, "mdxDeclaration", { enumerable: true, get: function () { return components_1.mdxDeclaration; } });
+var category_1 = require("./category");
+Object.defineProperty(exports, "generateIndexMetafile", { enumerable: true, get: function () { return category_1.generateIndexMetafile; } });
 const formatMDXBadge = ({ text, classname }) => {
-    return `<Badge class="badge ${classname}" text="${text}"/>`;
+    const style = typeof classname === "string" ? `badge--${classname.toLowerCase()}` : "";
+    return `<Badge class="badge ${DEFAULT_CSS_CLASSNAME} ${style}" text="${text}"/>`;
 };
 exports.formatMDXBadge = formatMDXBadge;
+/**
+ * Formats an admonition block in MDX format
+ * @param param - The admonition configuration object
+ * @param meta - Optional metadata for generator configuration
+ * @returns Formatted MDX string for the admonition
+ */
 const formatMDXAdmonition = ({ text, title, type }, meta) => {
     const isDocusaurus = meta?.generatorFrameworkName === "docusaurus";
     if (isDocusaurus && meta.generatorFrameworkVersion?.startsWith("2")) {
@@ -19,21 +38,42 @@ const formatMDXAdmonition = ({ text, title, type }, meta) => {
     return `${MARKDOWN_EOP}:::${type}[${title}]${text}:::`;
 };
 exports.formatMDXAdmonition = formatMDXAdmonition;
+/**
+ * Creates a bullet point element in MDX format
+ * @param text - Optional text to append after the bullet point
+ * @returns Formatted MDX string for the bullet point
+ */
 const formatMDXBullet = (text = "") => {
     return `<Bullet />${text}`;
 };
 exports.formatMDXBullet = formatMDXBullet;
+/**
+ * Creates a collapsible details section in MDX format
+ * @param param - The collapsible section configuration
+ * @returns Formatted MDX string for the collapsible section
+ */
 const formatMDXDetails = ({ dataOpen, dataClose, }) => {
     return `${MARKDOWN_EOP}<Details dataOpen="Hide ${dataOpen}" dataClose="Show ${dataClose}">${MARKDOWN_EOP}\r${MARKDOWN_EOP}</Details>${MARKDOWN_EOP}`;
 };
 exports.formatMDXDetails = formatMDXDetails;
+/**
+ * Creates a link to the specification documentation
+ * @param url - The URL to the specification
+ * @returns Formatted MDX string for the specification link
+ */
 const formatMDXSpecifiedByLink = (url) => {
     return `<SpecifiedBy url="${url}"/>`;
 };
 exports.formatMDXSpecifiedByLink = formatMDXSpecifiedByLink;
+/**
+ * Formats a name entity with optional parent type
+ * @param name - The name to format
+ * @param parentType - Optional parent type to prefix the name
+ * @returns Formatted MDX string for the name entity
+ */
 const formatMDXNameEntity = (name, parentType) => {
     const parentName = parentType ? `${parentType}.` : "";
-    return `<code style={{ fontWeight: 'normal' }}>${parentName}<b>${name}</b></code>`;
+    return `<code style={{ fontWeight: 'normal' }}>${(0, utils_1.escapeMDX)(parentName)}<b>${(0, utils_1.escapeMDX)(name)}</b></code>`;
 };
 exports.formatMDXNameEntity = formatMDXNameEntity;
 const formatMDXLink = ({ text, url }) => {

package/package.json

@@ -5,7 +5,7 @@
   "bugs": {
     "url": "https://github.com/graphql-markdown/graphql-markdown/issues"
   },
-  "version": "1.28.0",
+  "version": "1.29.1",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -65,12 +65,14 @@
     "docs": "typedoc"
   },
   "dependencies": {
-    "@graphql-markdown/cli": "^0.2.0",
+    "@graphql-markdown/cli": "^0.3.1",
+    "@graphql-markdown/logger": "^1.0.5",
+    "@graphql-markdown/utils": "^1.8.1",
     "@docusaurus/utils": ">=3.2.0"
   },
   "devDependencies": {
     "@docusaurus/types": "^3.7.0",
-    "@graphql-markdown/types": "^1.6.0"
+    "@graphql-markdown/types": "^1.7.0"
   },
   "peerDependencies": {
     "@docusaurus/logger": "*"