@xyd-js/content 0.1.0-xyd.10

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@xyd-js/content",
+  "version": "0.1.0-xyd.10",
+  "description": "",
+  "main": "./dist/index.js",
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": "./dist/index.js",
+    "./vite": "./dist/vite.js",
+    "./md": "./dist/md.js"
+  },
+  "dependencies": {
+    "@mdx-js/mdx": "^3.1.0",
+    "@mdx-js/rollup": "^3.0.1",
+    "estree-util-is-identifier-name": "^3.0.0",
+    "estree-util-value-to-estree": "^3.1.2",
+    "gray-matter": "^4.0.3",
+    "mdast": "^3.0.0",
+    "mdast-util-mdx": "^3.0.0",
+    "mdast-util-mdx-jsx": "^3.1.3",
+    "mdast-util-to-string": "^4.0.0",
+    "remark-directive": "^3.0.0",
+    "remark-frontmatter": "^5.0.0",
+    "remark-gfm": "^4.0.0",
+    "remark-mdx-frontmatter": "^5.0.0",
+    "unified": "^11.0.5",
+    "unist-util-visit": "^5.0.0",
+    "vfile": "^6.0.3",
+    "@xyd-js/core": "0.1.0-xyd.9"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.8",
+    "rimraf": "^3.0.2",
+    "tsup": "^8.3.0",
+    "typescript": "^4.5.5",
+    "vite": "^6.0.7"
+  },
+  "scripts": {
+    "clean": "rimraf build",
+    "prebuild": "pnpm clean",
+    "build": "tsup",
+    "watch": "tsup --watch"
+  }
+}

package/packages/md/index.ts

@@ -0,0 +1,13 @@
+import {RemarkMdxTocOptions} from "./plugins/mdToc";
+import {defaultPlugins} from "./plugins"
+
+export {RemarkMdxTocOptions} from "./plugins/mdToc";
+
+export function mdOptions(toc: RemarkMdxTocOptions) {
+    return {
+        remarkPlugins: [
+            ...defaultPlugins(toc)
+        ],
+        rehypePlugins: []
+    }
+}

package/packages/md/plugins/index.ts

@@ -0,0 +1,26 @@
+import remarkFrontmatter from "remark-frontmatter";
+import remarkMdxFrontmatter from "remark-mdx-frontmatter";
+import remarkGfm from "remark-gfm";
+import remarkDirective from 'remark-directive'
+
+import {remarkMdxToc, RemarkMdxTocOptions} from "./mdToc";
+import {remarkInjectCodeMeta} from "./mdCode";
+import {extractThemeSettings} from "./mdThemeSettings";
+import {extractPage} from "./mdPage";
+import {mdCodeGroup} from "./mdCodeGroup";
+import {remarkDirectiveWithMarkdown} from "./mdComponentDirective";
+
+export function defaultPlugins(toc: RemarkMdxTocOptions) {
+    return [
+        remarkFrontmatter,
+        remarkMdxFrontmatter,
+        remarkGfm,
+        remarkDirective,
+        remarkMdxToc(toc),
+        remarkInjectCodeMeta,
+        extractThemeSettings,
+        extractPage,
+        mdCodeGroup,
+        remarkDirectiveWithMarkdown
+    ]
+}

package/packages/md/plugins/mdCode.ts

@@ -0,0 +1,19 @@
+import {visit} from "unist-util-visit";
+
+/**
+ * This plugin injects the code meta into the code node's data
+ * so that it can be used in the code block component
+ */
+export function remarkInjectCodeMeta() {
+    return (tree: any) => {
+        visit(tree, 'code', (node) => {
+            if (node.meta) {
+                node.data = node.data || {};
+                node.data.hProperties = {
+                    ...(node.data.hProperties || {}),
+                    meta: node.meta,
+                };
+            }
+        });
+    };
+}

package/packages/md/plugins/mdCodeGroup.ts

@@ -0,0 +1,40 @@
+import {visit} from 'unist-util-visit';
+
+/**
+ * This plugin transforms a custom container directive into a JSX node
+ * https://github.com/remarkjs/remark-directive is needed to parse the container directive
+ */
+export function mdCodeGroup() {
+    return (tree: any) => {
+        visit(tree, 'containerDirective', (node) => {
+            // TODO: is `code-group` ok name? -> rename to CodeSample? or use `mdComponentDirective` instead
+            if (node.name !== 'code-group') {
+                return
+            }
+
+            const description = node.attributes?.title || '';
+            const codeblocks = [];
+
+            for (const child of node.children) {
+                if (child.type === 'code') {
+                    const meta = child.meta || '';
+                    const value = child.value || '';
+                    const lang = child.lang || '';
+
+                    codeblocks.push({value, lang, meta});
+                }
+            }
+
+            // Add metadata to the node
+            node.data = {
+                hName: 'DirectiveCodeSample',
+                hProperties: {
+                    description,
+                    codeblocks: JSON.stringify(codeblocks),
+                },
+            };
+
+            node.children = [];
+        });
+    };
+}

package/packages/md/plugins/mdComponentDirective.ts

@@ -0,0 +1,141 @@
+import {Plugin, unified} from "unified";
+import remarkParse from "remark-parse";
+import remarkMdx from "remark-mdx";
+import {visit} from "unist-util-visit";
+import {Node as UnistNode} from "unist";
+
+function toPascalCase(str: string) {
+    return str
+        .replace(/([a-z])([A-Z])/g, "$1 $2") // Add space before capital letters
+        .replace(/[^a-zA-Z0-9]/g, " ") // Replace special characters with space
+        .split(" ") // Split by space
+        .map(word => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()) // Capitalize first letter
+        .join("");
+}
+
+
+const supportedDirectives: { [key: string]: boolean } = {
+    Details: true,
+    details: true,
+
+    Table: true,
+    table: true,
+
+    Subtitle: true,
+    subtitle: true,
+}
+
+const tableComponents: { [key: string]: boolean } = {
+    Table: true,
+    table: true
+}
+
+const parseMarkdown = (content: string) => {
+    const ast = unified()
+        .use(remarkParse)
+        .use(remarkMdx)
+        .parse(content);
+    return ast.children;
+};
+
+export const remarkDirectiveWithMarkdown: Plugin = () => {
+    return (tree: UnistNode) => {
+        visit(tree, 'containerDirective', (node: any) => {
+            if (!supportedDirectives[node.name]) {
+                return;
+            }
+
+            const isTable = tableComponents[node.name];
+            const attributes = [];
+
+            // TODO: MORE GENERIC CUZ IT HAS IMPL DETAILS OF TABLE
+            if (isTable) {
+                // TODO: support tsx tables like: [<>`Promise<Reference[]>`</>] ?
+                const tableData = JSON.parse(node.children[0].value);
+                const [header, ...rows] = tableData;
+
+                const jsxNode = {
+                    type: 'mdxJsxFlowElement',
+                    name: 'Table',
+                    attributes: [],
+                    children: [
+                        {
+                            type: 'mdxJsxFlowElement',
+                            name: 'Table.Head',
+                            attributes: [],
+                            children: [
+                                {
+                                    type: 'mdxJsxFlowElement',
+                                    name: 'Table.Tr',
+                                    attributes: [],
+                                    children: header.map((cell: string) => ({
+                                        type: 'mdxJsxFlowElement',
+                                        name: 'Table.Th',
+                                        attributes: [],
+                                        children: parseMarkdown(cell)
+                                    }))
+                                }
+                            ]
+                        },
+                        // TODO: Table.Cell ?
+                        ...rows.map((row: string[]) => ({
+                            type: 'mdxJsxFlowElement',
+                            name: 'Table.Tr',
+                            attributes: [],
+                            children: row.map((cell: string) => ({
+                                type: 'mdxJsxFlowElement',
+                                name: 'Table.Td',
+                                attributes: [],
+                                children: parseMarkdown(cell)
+                            }))
+                        }))
+                    ]
+                };
+
+                Object.assign(node, jsxNode);
+                return;
+            }
+
+            if (node.attributes) {
+                const jsxProps = []
+
+                for (let [key, value] of Object.entries(node.attributes)) {
+                    if (typeof value === "string" && !value.startsWith("<")) {
+                        attributes.push({
+                            type: 'mdxJsxAttribute',
+                            name: key,
+                            value: value
+                        });
+                    } else {
+                        jsxProps.push(`${key}={${value}}`)
+
+                    }
+                }
+
+                const mdxString = `<Fragment ${jsxProps.join(" ")}></Fragment>`
+
+                const ast = unified()
+                    .use(remarkParse)
+                    .use(remarkMdx)
+                    .parse(mdxString);
+
+                if (ast && ast.children[0] && ast.children[0].attributes) {
+                    for (const attr of ast.children[0].attributes) {
+                        // TODO: support markdown also e.g Hello `World` - currently it mus be: Hello <code>World</code>
+                        attributes.push(attr);
+                    }
+                }
+            }
+
+            const jsxNode = {
+                type: 'mdxJsxFlowElement',
+                name: toPascalCase(node.name),
+                attributes: attributes,
+                children: node.children
+            };
+
+            Object.assign(node, jsxNode);
+        });
+    }
+}
+

package/packages/md/plugins/mdPage.ts

@@ -0,0 +1,32 @@
+import {Plugin} from 'unified';
+import {Node as UnistNode} from 'unist';
+import {visit} from 'unist-util-visit';
+
+declare global {
+    var page: boolean | null | undefined
+}
+
+/**
+ * This plugin extracts the `page` variable from the markdown file.
+ * This variable(`page`) is used to determine if theme should be dropped out.
+ *
+ * It means that if page=true, theme is not used, and we can use the markdown file as a standalone page.
+ */
+export const extractPage: Plugin = () => {
+    return (tree: UnistNode) => {
+        visit(tree, 'exportNamedDeclaration', (node: any) => {
+            const declaration = node.declaration;
+
+            if (!declaration || !declaration.declarations || !declaration.declarations.length) {
+                return;
+            }
+
+            // seek declarations like export const page = true in md files
+            declaration.declarations.forEach((decl: any) => {
+                if (decl.id.name === 'page') {
+                    global.page = decl.init as boolean;
+                }
+            });
+        });
+    };
+};

package/packages/md/plugins/mdThemeSettings.ts

@@ -0,0 +1,30 @@
+import {Plugin} from 'unified';
+import {Node as UnistNode} from 'unist';
+import {visit} from 'unist-util-visit';
+
+interface ThemeSettings {
+    bigArticle: boolean;
+}
+
+declare global {
+    var themeSettings: ThemeSettings | undefined;
+}
+
+/**
+ * This plugin adds the `themeSettings` variable to the global scope.
+ * This variable is used to determine the theme settings for the current page.
+ */
+export const extractThemeSettings: Plugin = () => {
+    return (tree: UnistNode) => {
+        visit(tree, 'exportNamedDeclaration', (node: any) => {
+            const declaration = node.declaration;
+            if (declaration && declaration.declarations) {
+                declaration.declarations.forEach((decl: any) => {
+                    if (decl.id.name === 'themeSettings') {
+                        global.themeSettings = decl.init as ThemeSettings;
+                    }
+                });
+            }
+        });
+    };
+};

package/packages/md/plugins/mdToc.ts

@@ -0,0 +1,133 @@
+import {Root, Heading} from "mdast";
+import {MdxjsEsm} from "mdast-util-mdx";
+import {Plugin} from "unified"; // TODO: use Plugin type
+import {MdxJsxFlowElement, MdxJsxAttribute} from "mdast-util-mdx-jsx";
+
+export type TocEntry = {
+    depth: number,
+    value: string,
+    attributes: { [key: string]: string },
+    children: TocEntry[]
+};
+
+export type CustomTag = {
+    name: RegExp,
+    depth: (name: string) => number
+};
+
+export interface RemarkMdxTocOptions {
+    name?: string,
+    customTags?: CustomTag[],
+    minDepth?: number
+}
+
+// TODO: fix any
+export const remarkMdxToc = (options: RemarkMdxTocOptions): Plugin => () => async (ast: any) => {
+    const {visit} = await import("unist-util-visit");
+    const {toString} = await import("mdast-util-to-string");
+    const {valueToEstree} = await import('estree-util-value-to-estree')
+    const {name: isIdentifierName} = await import('estree-util-is-identifier-name');
+
+    const mdast = ast as Root;
+    const name = options.name ?? "toc";
+    if (!isIdentifierName(name)) {
+        throw new Error(`Invalid name for an identifier: ${name}`);
+    }
+
+    const toc: TocEntry[] = [];
+    const flatToc: TocEntry[] = [];
+    const createEntry = (node: Heading | MdxJsxFlowElement, depth: number): TocEntry => {
+        let attributes = (node.data || {}) as TocEntry['attributes'];
+        if (node.type === "mdxJsxFlowElement") {
+            attributes = Object.fromEntries(
+                node.attributes
+                    .filter(attribute => attribute.type === 'mdxJsxAttribute' && typeof attribute.value === 'string')
+                    .map(attribute => [(attribute as MdxJsxAttribute).name, attribute.value])
+            ) as TocEntry['attributes'];
+        }
+        return {
+            depth,
+            value: toString(node, {includeImageAlt: false}),
+            attributes,
+            children: []
+        }
+    };
+
+    visit(mdast, ["heading", "mdxJsxFlowElement"], node => {
+        let depth = 0;
+        if (node.type === "mdxJsxFlowElement") {
+            let valid = false;
+            if (/^h[1-6]$/.test(node.name || "")) {
+                valid = true;
+                depth = parseInt(node.name!.substring(1));
+            } else if (options.customTags) {
+                for (const tag of options.customTags) {
+                    if (tag.name.test(node.name || "")) {
+                        valid = true;
+                        depth = tag.depth(node.name || "");
+                        break;
+                    }
+                }
+            }
+
+            if (!valid) {
+                return;
+            }
+        } else if (node.type === "heading") {
+            depth = node.depth;
+        } else {
+            return;
+        }
+
+        if (depth && (options?.minDepth && options.minDepth > depth)) {
+            return
+        }
+
+        const entry = createEntry(node, depth);
+        flatToc.push(entry);
+
+        let parent: TocEntry[] = toc;
+        for (let i = flatToc.length - 1; i >= 0; --i) {
+            const current = flatToc[i];
+            if (current.depth < entry.depth) {
+                parent = current.children;
+                break;
+            }
+        }
+        parent.push(entry);
+    });
+
+    const tocExport: MdxjsEsm = {
+        type: "mdxjsEsm",
+        value: "",
+        data: {
+            estree: {
+                type: "Program",
+                sourceType: "module",
+                body: [
+                    {
+                        type: "ExportNamedDeclaration",
+                        specifiers: [],
+                        attributes: [],
+                        source: null,
+                        declaration: {
+                            type: "VariableDeclaration",
+                            kind: "const",
+                            declarations: [
+                                {
+                                    type: "VariableDeclarator",
+                                    id: {
+                                        type: "Identifier",
+                                        name
+                                    },
+                                    init: valueToEstree(toc)
+                                }
+                            ]
+                        }
+                    }
+                ]
+            }
+        }
+    };
+    mdast.children.unshift(tocExport);
+};

package/packages/vite/index.ts

@@ -0,0 +1,14 @@
+import type {Plugin} from 'rollup';
+import mdx from '@mdx-js/rollup';
+
+import {RemarkMdxTocOptions, mdOptions} from "../md";
+
+export interface VitePluginInterface {
+    toc: RemarkMdxTocOptions
+}
+
+export function vitePlugins(options: VitePluginInterface): Plugin[] {
+    return [
+        mdx(mdOptions(options.toc)),
+    ];
+}

package/src/fs.ts

@@ -0,0 +1,43 @@
+import {promises as fs} from "fs";
+import path from "path";
+
+import {VFile} from "vfile";
+import {compile as mdxCompile} from "@mdx-js/mdx";
+
+import {mdOptions} from "../packages/md";
+
+export async function compileBySlug(
+    slug: string,
+    mdx: boolean
+): Promise<string> {
+    // TODO: cwd ?
+    const filePath = path.join(process.cwd(), `${slug}.${mdx ? "mdx" : "md"}`)
+
+    await fs.access(filePath)
+
+    const content = await fs.readFile(filePath, "utf-8");
+
+    return await compile(content, filePath)
+}
+
+async function compile(content: string, filePath: string): Promise<string> {
+    const vfile = new VFile({
+        path: filePath,
+        value: content,
+        contents: content
+    });
+
+    const opt = mdOptions({
+        minDepth: 2 // TODO: configurable?
+    })
+
+    const compiled = await mdxCompile(vfile, {
+        remarkPlugins: opt.remarkPlugins,
+        rehypePlugins: opt.rehypePlugins,
+        recmaPlugins: [],
+        outputFormat: 'function-body',
+        development: false,
+    });
+
+    return String(compiled)
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export {
+    compileBySlug
+} from "./fs"
+
+export {
+    pageFrontMatters,
+    filterNavigationByLevels
+} from "./navigation"