@terrafirmagreg-team/mdx 1.2.4 → 1.2.6

package/src/lib/mdx/entries/entity.ts

@@ -0,0 +1,6 @@
+import { createEntryRemark } from './factory.ts';
+
+export const remarkEntityEntry = createEntryRemark({
+  directive: 'entity',
+  component: 'EntityEntry',
+});

package/src/lib/mdx/entries/factory.ts

@@ -0,0 +1,102 @@
+import {
+  contentChildren,
+  extractDirectiveLabel,
+  extractLeafLabel,
+  estreeBoolean,
+  estreeString,
+  jsxAttr,
+  jsxExpression,
+  walkDirectives,
+  type DirectiveNode,
+  type JsxAttribute,
+  type MdastNode,
+} from '../directive-utils.ts';
+
+export type EntrySpec = {
+  directive: string;
+  component: string;
+  leafKey?: string;
+  labelAttr?: string;
+  usePagePack?: boolean;
+  transform?: (ctx: {
+    directive: DirectiveNode;
+    attrs: JsxAttribute[];
+    children: MdastNode[];
+    isLeaf: boolean;
+    file: { path?: string };
+  }) => MdastNode[] | void;
+};
+
+function pageDataset(file: { path?: string }): string | undefined {
+  return file.path
+    ?.replaceAll('\\', '/')
+    .match(/content\/docs\/([^/]+)\/[^/]+\//)?.[1];
+}
+
+export function toAttributes(directive: DirectiveNode): JsxAttribute[] {
+  return Object.entries(directive.attributes ?? {}).map(([name, value]) => ({
+    type: 'mdxJsxAttribute' as const,
+    name,
+    value:
+      value == null || value === ''
+        ? jsxExpression(estreeBoolean(true))
+        : typeof value === 'string'
+          ? value
+          : jsxExpression(estreeString(String(value))),
+  }));
+}
+
+export function createEntryRemark(spec: EntrySpec) {
+  const {
+    directive: name,
+    component,
+    leafKey = 'id',
+    labelAttr = 'label',
+    usePagePack = false,
+    transform,
+  } = spec;
+
+  return function remark() {
+    return (tree: MdastNode, file: { path?: string }) => {
+      walkDirectives(tree, (directive) => {
+        if (directive.name !== name) return;
+        if (
+          directive.type !== 'leafDirective' &&
+          directive.type !== 'containerDirective'
+        )
+          return;
+
+        const attrs = toAttributes(directive);
+        const pack = usePagePack ? pageDataset(file) : undefined;
+        if (
+          pack &&
+          directive.attributes?.pack == null &&
+          directive.attributes?.defaultPack == null
+        ) {
+          attrs.push(jsxAttr('defaultPack', pack));
+        }
+
+        const isLeaf = directive.type === 'leafDirective';
+        const label = (
+          isLeaf
+            ? extractLeafLabel(directive)
+            : extractDirectiveLabel(directive)
+        ).trim();
+        const key = isLeaf ? leafKey : labelAttr;
+        if (label && key) attrs.unshift(jsxAttr(key, label));
+
+        const children = isLeaf ? [] : contentChildren(directive);
+        const out =
+          transform?.({ directive, attrs, children, isLeaf, file }) ??
+          children;
+
+        Object.assign(directive, {
+          type: 'mdxJsxFlowElement',
+          name: component,
+          attributes: attrs,
+          children: out,
+        });
+      });
+    };
+  };
+}

package/src/lib/mdx/entries/fluid.ts

@@ -0,0 +1,6 @@
+import { createEntryRemark } from './factory.ts';
+
+export const remarkFluidEntry = createEntryRemark({
+  directive: 'fluid',
+  component: 'FluidEntry',
+});

package/src/lib/mdx/entries/guide.ts

@@ -0,0 +1,6 @@
+import { createEntryRemark } from './factory.ts';
+
+export const remarkGuideEntry = createEntryRemark({
+  directive: 'guide',
+  component: 'GuideEntry',
+});

package/src/lib/mdx/entries/image.ts

@@ -0,0 +1,9 @@
+import { createEntryRemark } from './factory.ts';
+
+export const remarkImageEntry = createEntryRemark({
+  directive: 'image',
+  component: 'DocsImage',
+  leafKey: 'src',
+  labelAttr: 'alt',
+  usePagePack: true,
+});

package/src/lib/mdx/entries/index.ts

@@ -0,0 +1,45 @@
+import type { MdastNode } from '../directive-utils.ts';
+import { remarkBlockEntry } from './block.ts';
+import { remarkEntityEntry } from './entity.ts';
+import { remarkFluidEntry } from './fluid.ts';
+import { remarkGuideEntry } from './guide.ts';
+import { remarkImageEntry } from './image.ts';
+import { remarkItemEntry } from './item.ts';
+import { remarkMultiblockEntry } from './multiblock.ts';
+import { remarkQuestEntry } from './quest.ts';
+import { remarkRecipeEntry } from './recipe.ts';
+import { remarkStoryEntry } from './story.ts';
+import { remarkTagEntry } from './tag.ts';
+
+export { remarkBlockEntry } from './block.ts';
+export { remarkEntityEntry } from './entity.ts';
+export { remarkFluidEntry } from './fluid.ts';
+export { remarkGuideEntry } from './guide.ts';
+export { remarkImageEntry } from './image.ts';
+export { remarkItemEntry } from './item.ts';
+export { remarkMultiblockEntry } from './multiblock.ts';
+export { remarkQuestEntry } from './quest.ts';
+export { remarkRecipeEntry } from './recipe.ts';
+export { remarkStoryEntry } from './story.ts';
+export { remarkTagEntry } from './tag.ts';
+
+const ALL = [
+  remarkItemEntry,
+  remarkBlockEntry,
+  remarkFluidEntry,
+  remarkEntityEntry,
+  remarkTagEntry,
+  remarkQuestEntry,
+  remarkGuideEntry,
+  remarkMultiblockEntry,
+  remarkImageEntry,
+  remarkStoryEntry,
+  remarkRecipeEntry,
+];
+
+export function remarkEntries() {
+  const plugins = ALL.map((factory) => factory());
+  return (tree: MdastNode, file: { path?: string }) => {
+    for (const plugin of plugins) plugin(tree, file);
+  };
+}

package/src/lib/mdx/entries/item.ts

@@ -0,0 +1,6 @@
+import { createEntryRemark } from './factory.ts';
+
+export const remarkItemEntry = createEntryRemark({
+  directive: 'item',
+  component: 'ItemEntry',
+});

package/src/lib/mdx/entries/multiblock.ts

@@ -0,0 +1,16 @@
+import { jsxAttr, type MdastNode } from '../directive-utils.ts';
+import { createEntryRemark } from './factory.ts';
+
+export const remarkMultiblockEntry = createEntryRemark({
+  directive: 'multiblock',
+  component: 'Multiblock',
+  transform({ directive, attrs, isLeaf }) {
+    if (isLeaf) return;
+    const code = directive.children?.find(
+      (child) => child.type === 'code',
+    ) as { value?: string } | undefined;
+    if (!code?.value) return;
+    attrs.unshift(jsxAttr('spec', code.value));
+    return [] as MdastNode[];
+  },
+});

package/src/lib/mdx/entries/quest.ts

@@ -0,0 +1,6 @@
+import { createEntryRemark } from './factory.ts';
+
+export const remarkQuestEntry = createEntryRemark({
+  directive: 'quest',
+  component: 'QuestEntry',
+});

package/src/lib/mdx/entries/recipe.ts

@@ -0,0 +1,6 @@
+import { createEntryRemark } from './factory.ts';
+
+export const remarkRecipeEntry = createEntryRemark({
+  directive: 'recipe',
+  component: 'RecipeEntry',
+});

package/src/lib/mdx/entries/story.ts

@@ -0,0 +1,6 @@
+import { createEntryRemark } from './factory.ts';
+
+export const remarkStoryEntry = createEntryRemark({
+  directive: 'story',
+  component: 'Story', leafKey: 'name',
+});

package/src/lib/mdx/entries/tag.ts

@@ -0,0 +1,6 @@
+import { createEntryRemark } from './factory.ts';
+
+export const remarkTagEntry = createEntryRemark({
+  directive: 'tag',
+  component: 'TagEntry',
+});

package/src/lib/mdx/files.ts

@@ -0,0 +1,129 @@
+import type {
+  FileNode,
+  FolderNode,
+  ToMdxOptions,
+} from 'fumadocs-core/mdx-plugins/remark-mdx-files';
+import { toString } from 'mdast-util-to-string';
+import { visit } from 'unist-util-visit';
+import type { DirectiveNode } from './directive-utils.ts';
+import type { JsxAttribute, JsxElement, MdastNode } from '../../types/mdx';
+
+type TreeNode = FileNode | FolderNode;
+
+const LINK_RE = /^\[([^\]]+)\]\((\S+?)(?:\s+"([^"]*)")?\)$/;
+
+type TreeName = { name: string; href?: string; description?: string };
+
+function parseName(raw: string): TreeName {
+  const match = LINK_RE.exec(raw.trim());
+  if (!match) return { name: raw };
+  const [, text, href, description] = match;
+  const out: TreeName = { name: text, href };
+  if (description) out.description = description;
+  return out;
+}
+
+function attributes(parsed: TreeName): JsxAttribute[] {
+  const attrs: JsxAttribute[] = [
+    { type: 'mdxJsxAttribute', name: 'name', value: parsed.name },
+  ];
+  if (parsed.href)
+    attrs.push({ type: 'mdxJsxAttribute', name: 'href', value: parsed.href });
+  if (parsed.description)
+    attrs.push({
+      type: 'mdxJsxAttribute',
+      name: 'description',
+      value: parsed.description,
+    });
+  return attrs;
+}
+
+function nodeToMdx(node: TreeNode, options: ToMdxOptions): JsxElement {
+  const parsed = parseName(node.name);
+  const attrs = attributes(parsed);
+  const isFolder = node.type === 'folder' || parsed.name.endsWith('/');
+  if (!isFolder)
+    return {
+      type: 'mdxJsxFlowElement',
+      name: 'File',
+      attributes: attrs,
+      children: [],
+    };
+  if (options.defaultOpenAll)
+    attrs.push({ type: 'mdxJsxAttribute', name: 'defaultOpen', value: true });
+  const children =
+    node.type === 'folder'
+      ? node.children.map((item) => nodeToMdx(item, options) as unknown as MdastNode)
+      : [];
+  return {
+    type: 'mdxJsxFlowElement',
+    name: 'Folder',
+    attributes: attrs,
+    children,
+  };
+}
+
+export function filesToMdx(node: TreeNode, options: ToMdxOptions): JsxElement {
+  return {
+    type: 'mdxJsxFlowElement',
+    name: 'Files',
+    attributes: [],
+    children:
+      node.type === 'folder' && node.name === ''
+        ? node.children.map((item) => nodeToMdx(item, options) as unknown as MdastNode)
+        : [nodeToMdx(node, options) as unknown as MdastNode],
+  };
+}
+
+type ListNode = MdastNode & { children?: MdastNode[] };
+
+function itemToTree(item: ListNode): TreeNode {
+  const paragraph = item.children?.find((c) => c.type === 'paragraph');
+  const nested = item.children?.find((c) => c.type === 'list');
+  const link =
+    paragraph?.children?.length === 1 &&
+    paragraph.children[0].type === 'link'
+      ? (paragraph.children[0] as unknown as {
+          url: string;
+          title?: string | null;
+          children: { value: string }[];
+        })
+      : undefined;
+  let name = link ? toString(link.children[0] as never) : toString(paragraph as never);
+  const href = link?.url;
+  const description = link?.title ?? undefined;
+  const annotated = href ? `[${name}](${href}${description ? ` "${description}"` : ''})` : name;
+  const isFolder = !!nested || name.endsWith('/');
+  if (isFolder) name = name.replace(/\/+$/, '') || name;
+  if (!isFolder) return { type: 'file', name: annotated } as FileNode;
+  const children = (nested?.children ?? []).map(
+    (child) => itemToTree(child as ListNode) as TreeNode,
+  );
+  return {
+    type: 'folder',
+    name: href ? `[${name}/](${href}${description ? ` "${description}"` : ''})` : name,
+    children,
+  } as FolderNode;
+}
+
+export function remarkFilesDirective() {
+  return (tree: MdastNode) => {
+    visit(tree as never, 'containerDirective', (node) => {
+      const directive = node as DirectiveNode;
+      if (directive.name !== 'files') return;
+      const children = (directive.children ?? []).flatMap((child) =>
+        child.type === 'list' ? (child.children ?? []) : [],
+      );
+      if (!children.length) return;
+      const root: FolderNode = {
+        type: 'folder',
+        name: '',
+        children: children.map((item) => itemToTree(item as ListNode)),
+      } as FolderNode;
+      Object.assign(
+        directive,
+        filesToMdx(root, { defaultOpenAll: true }),
+      );
+    });
+  };
+}

package/src/lib/mdx/{references.ts → github-autolinks.ts}

@@ -3,6 +3,7 @@ type MdastNode = {
   value?: string;
   url?: string;
   children?: MdastNode[];
+  data?: { hProperties?: Record<string, unknown> };
 };
 
 const ISSUE_REF = /^#\d+$/;
@@ -18,12 +19,21 @@ const SKIP = new Set([
   'html',
 ]);
 
-const CHANGELOG_PATH = /[/\\]changelog[/\\]([^/\\]+)[/\\]/;
+const DEFAULT_PATHS = [
+  /[/\\]changelog[/\\]([^/\\]+)[/\\]/,
+  /[/\\]docs[/\\]([^/\\]+)[/\\][^/\\]+[/\\]major-changelogs[/\\]/,
+];
 
-export function remarkChangelogReferences(options: { datasetConfig?: Record<string, { repo?: string }> } = {}) {
-  const datasetConfig = options.datasetConfig ?? {};
+export function remarkGithubAutolinks(options: {
+  datasetConfig?: Record<string, { repo?: string }>;
+  paths?: RegExp[];
+} = {}) {
+  const { datasetConfig = {}, paths = DEFAULT_PATHS } = options;
   return (tree: MdastNode, file: { path?: string }) => {
-    const pack = CHANGELOG_PATH.exec(file.path ?? '')?.[1];
+    const filePath = file.path ?? '';
+    const pack = paths
+      .map((pattern) => pattern.exec(filePath)?.[1])
+      .find(Boolean);
     const repo = pack ? datasetConfig[pack]?.repo : undefined;
     if (!repo) return;
     const repoUrl = `https://github.com/${repo}`;
@@ -40,12 +50,14 @@ export function remarkChangelogReferences(options: { datasetConfig?: Record<stri
                 type: 'link',
                 url: `${repoUrl}/issues/${part.slice(1)}`,
                 children: [{ type: 'text', value: part }],
+                data: { hProperties: { className: 'gh-issue' } },
               }
             : USER_REF.test(part)
               ? {
                   type: 'link',
                   url: `https://github.com/${part.slice(1)}`,
                   children: [{ type: 'text', value: part }],
+                  data: { hProperties: { className: 'gh-mention' } },
                 }
               : { type: 'text', value: part },
         );
@@ -54,4 +66,3 @@ export function remarkChangelogReferences(options: { datasetConfig?: Record<stri
     visit(tree);
   };
 }
-

package/src/lib/mdx/tabs.ts

@@ -14,7 +14,6 @@ export function remarkTabs() {
     walkContainers(tree, (directive) => {
       if (directive.name !== 'tabs') return;
       toTabs(directive);
-      return false;
     });
   };
 }

package/src/lib/story-remark.ts

@@ -12,6 +12,7 @@ export type DirectiveMeta = {
   multiline?: string[];
   props?: string[];
   solo?: boolean;
+  paired?: boolean;
   descriptions?: Record<string, string>;
   raw?: string;
   variants?: Record<string, Partial<DirectiveMeta>>;
@@ -89,30 +90,25 @@ const DIRECTIVE_META: Record<string, DirectiveMeta> = {
       strokeWidth: 'Lucide stroke width, default 2',
     },
   },
-  'gradient-text': {
-    name: 'gradient',
-    label: 'children',
-    colon: 1,
-    props: ['from', 'to', 'image', 'children', 'className'],
+  gradient: {
+    colon: 2,
+    paired: true,
+    multiline: ['children'],
+    props: ['from', 'to', 'dir', 'image', 'children', 'className'],
     descriptions: {
       from: 'Gradient start color',
       to: 'Gradient end color',
+      dir: 'CSS gradient direction (to right, 135deg, …)',
       image: 'CSS image overriding the gradient',
-      children: 'Text content, the directive label',
+      children: 'Body markdown inside the ::gradient … :: block',
     },
   },
-  'glow-header': {
-    name: 'glow',
-    label: 'children',
-    colon: 1,
-    props: ['from', 'to', 'image', 'gradient', 'fade', 'children', 'className'],
+  video: {
+    colon: 2,
+    props: ['src', 'title', 'className'],
     descriptions: {
-      from: 'Gradient start color',
-      to: 'Gradient end color',
-      image: 'CSS image overriding the gradient',
-      gradient: 'Also tint the background box with the gradient',
-      fade: 'Gradient border along the bottom edge',
-      children: 'Header text, the directive label',
+      src: 'Embed URL (e.g. youtube-nocookie embed)',
+      title: 'Accessible frame title',
     },
   },
   callout: {
@@ -126,11 +122,20 @@ const DIRECTIVE_META: Record<string, DirectiveMeta> = {
       title: 'Overrides the default localized title',
       children: 'Body markdown',
     },
+    variants: {
+      Alert: {
+        raw: '> [!TIP]\nA GitHub alert blockquote.',
+      },
+    },
   },
   banner: {
     colon: 3,
     multiline: ['children'],
-    props: ['id', 'height', 'variant', 'rainbowColors', 'changeLayout', 'children', 'className'],
+    props: ['id', 'height', 'variant', 'gradient', 'from', 'to', 'dir', 'image', 'rainbowColors', 'changeLayout', 'children', 'className'],
+    descriptions: {
+      variant: 'normal | rainbow | fade (gradient ring, fades down) | glow (radial bg + shadow)',
+      gradient: 'Gradient-fill the title text',
+    },
   },
   tabs: {
     colon: 3,
@@ -147,7 +152,25 @@ const DIRECTIVE_META: Record<string, DirectiveMeta> = {
   },
   accordions: {
     colon: 3,
-    props: ['multiple', 'defaultValue', 'children', 'className'],
+    props: ['format', 'multiple', 'defaultValue', 'children', 'className'],
+    descriptions: {
+      format:
+        'Input format — details: single :::details[Title] block; accordions: :::accordions group with ::accordion[Title] items; jsx: raw <Accordions>/<Accordion> markup',
+    },
+    variants: {
+      Details: {
+        raw: ':::details[Summary]\nHidden content.\n:::',
+      },
+      Open: {
+        raw: ':::details[Summary]{open}\nHidden content.\n:::',
+      },
+      'Multiple': {
+        raw: ':::accordions{multiple}\n::accordion[First]\nContent one.\n::accordion[Second]\nContent two.\n:::',
+      },
+      'Nested': {
+        raw: '::::details[Outer]{open}\nBefore.\n:::accordions\n::accordion[Inner one]\nNested answer one.\n::accordion[Inner two]\nNested answer two.\n:::\n::::',
+      },
+    },
   },
   image: {
     label: 'alt',
@@ -171,7 +194,33 @@ const DIRECTIVE_META: Record<string, DirectiveMeta> = {
       ├── mods
       └── config
     `,
-    props: ['children'],
+    props: ['format', 'children'],
+    descriptions: {
+      format:
+        'Input format — list: :::files markdown list; fenced: ```files code block',
+      name: 'Entry name — file or folder label',
+      icon: 'Custom icon name or path',
+      href: 'Link target — renders the entry as an anchor',
+      description: 'Muted description line under the entry',
+      disabled: 'Folder only — renders the entry as non-interactive',
+      defaultOpen: 'Folder only — starts expanded',
+      children:
+        'Tree body — a ```files code fence or a :::files markdown list; items: [name](href "description"), trailing / or a nested list = folder',
+    },
+    variants: {
+      List: {
+        raw: ':::files\n- app/\n  - layout.tsx\n  - page.tsx\n- package.json\n:::',
+      },
+      Links: {
+        raw: ':::files\n- [modpack/](/docs/modern/modpack "Modpack guides")\n  - [optional-mods.md](/docs/modern/modpack/optional-mods "Extra compatible mods")\n  - kubejs/\n    - server_scripts\n    - startup_scripts\n- [pakku.json](https://pakku.readthedocs.io "Pakku config")\n:::',
+      },
+      Deep: {
+        raw: ':::files\n- content/\n  - docs/\n    - dev/\n      - components/\n        - index.md\n        - item.md\n        - meta.json\n      - meta.json\n  - index.mdx\n:::',
+      },
+      Fenced: {
+        raw: '```files\nTerraFirmaGreg\n├── mods\n└── config\n```',
+      },
+    },
   },
   code: {
     fence: 'ts',
@@ -322,12 +371,30 @@ const DIRECTIVE_META: Record<string, DirectiveMeta> = {
     },
   },
   math: {
-    body: ':math[e = mc^2]',
-    props: ['children', 'block'],
+    props: ['format', 'children', 'block'],
     multiline: ['children'],
     descriptions: {
-      children: 'KaTeX source, the `:math[…]` label',
-      block: 'Display block (`::math`/`:::math`) instead of inline `:math`',
+      format:
+        'Input syntax — inline: :math[…] or $…$; block: ::math[…] leaf, :::math container, ```math fence or $$…$$',
+      children: 'KaTeX source',
+      block: 'Display block instead of inline',
+    },
+    variants: {
+      Inline: { raw: ':math[e = mc^2]' },
+      Dollar: { raw: '$e = mc^2$' },
+      Leaf: {
+        raw: '::math[\\int_0^\\infty e^{-x^2}\\,dx = \\frac{\\sqrt{\\pi}}{2}]',
+      },
+      Block: {
+        raw: ':::math\n\\int_0^\\infty e^{-x^2}\\,dx = \\frac{\\sqrt{\\pi}}{2}\n:::',
+      },
+      Fenced: {
+        raw: '```math\n\\int_0^\\infty e^{-x^2}\\,dx = \\frac{\\sqrt{\\pi}}{2}\n```',
+      },
+      Aligned: {
+        raw: ':::math\n\\begin{aligned}\n\\nabla \\cdot \\vec{E} &= \\frac{\\rho}{\\varepsilon_0} \\\\\n\\nabla \\times \\vec{B} &= \\mu_0 \\vec{J}\n\\end{aligned}\n:::',
+      },
+      Display: { raw: '$$e = mc^2$$' },
     },
   },
 };
@@ -401,11 +468,10 @@ export function remarkFor(
   if (key === 'accordions') {
     return md`
       :::accordions${args.multiple ? '{multiple}' : ''}
-      ::accordion[Title one]
-      …
-
-      ::accordion[Title two]
-      …
+      ::accordion[First]
+      Content one.
+      ::accordion[Second]
+      Content two.
       :::
     `;
   }
@@ -460,9 +526,9 @@ export function remarkFor(
       ? `[${String(args[meta.label])}]`
       : '';
   const head = `${':'.repeat(meta.colon ?? 2)}${name}${label}${attrs ? `{${attrs}}` : ''}`;
-  if (meta.colon !== 3 || meta.solo) return head;
+  if (meta.solo || (meta.colon !== 3 && !meta.paired)) return head;
   const inner =
     typeof args.children === 'string' && args.children ? args.children : '…';
-  return `${head}\n${inner}\n:::`;
+  return `${head}\n${inner}\n${':'.repeat(meta.colon ?? 3)}`;
 }
 

package/src/lib/story.ts

@@ -1,11 +1,32 @@
 'use client';
 
 import { defineStoryFactory } from '@fumadocs/story/next/client';
+import type {
+  Story,
+  StoryOptions,
+} from '@fumadocs/story/next/client';
 import { DocsWithControl } from '../components/story-panel';
+import type { ComponentType } from 'react';
 
 export { md } from './md';
 
-export const { defineStory } = defineStoryFactory({
+const factory = defineStoryFactory({
   WithControl: DocsWithControl,
 });
 
+const registry = ((globalThis as Record<symbol, unknown>)[
+  Symbol.for('terrafirmagreg.mdx.stories')
+] ??= {}) as Record<string, Story>;
+
+export function defineStory<C extends ComponentType<any>>(
+  options: StoryOptions<C>,
+): Story<C> {
+  const story = factory.defineStory(options);
+  if (options.displayName)
+    registry[options.displayName] = story as Story;
+  return story;
+}
+
+export function storyFor(name: string): Story | undefined {
+  return registry[name];
+}