@umami/shiso 0.54.0 → 0.61.0

package/mdx.config.ts

@@ -0,0 +1,143 @@
+import mdx from '@mdx-js/rollup';
+import rehypeAutolinkHeadings from 'rehype-autolink-headings';
+import rehypeHighlight from 'rehype-highlight';
+import rehypeSlug from 'rehype-slug';
+import remarkFrontmatter from 'remark-frontmatter';
+import remarkGfm from 'remark-gfm';
+import remarkMdxFrontmatter from 'remark-mdx-frontmatter';
+import type { Plugin } from 'vite';
+import { type MdNode, toText, walkTree } from './src/lib/mdast.ts';
+import { remarkToc } from './src/lib/remark-toc.ts';
+
+const SYNTHETIC_FRAGMENT = 'data-shiso-synthetic-fragment';
+
+function remarkCodeTitles() {
+  return (tree: MdNode) => {
+    const visit = (node: MdNode) => {
+      if (node.type === 'code' && node.meta?.trim()) {
+        const meta = node.meta.trim();
+        const titleMatch = meta.match(/(?:^|\s)title=(?:"([^"]+)"|'([^']+)'|([^\s]+))/);
+        const title = titleMatch ? titleMatch[1] || titleMatch[2] || titleMatch[3] : meta;
+        const hProperties = (node.data?.hProperties || {}) as Record<string, unknown>;
+        node.data = {
+          ...node.data,
+          hProperties: { ...hProperties, 'data-title': title },
+        };
+      }
+
+      node.children?.forEach(visit);
+    };
+
+    visit(tree);
+  };
+}
+
+function rehypeWrapJsxForHighlighting() {
+  return (tree: MdNode) => {
+    walkTree(tree, node => {
+      if (node.tagName !== 'code') {
+        return;
+      }
+
+      const properties = (node.properties || {}) as Record<string, unknown>;
+      const className = properties.className;
+      const classes = Array.isArray(className) ? className.map(String) : [String(className || '')];
+      const source = toText(node);
+
+      if (!classes.some(value => /\blanguage-(?:jsx|tsx)\b/.test(value))) {
+        return;
+      }
+
+      if (!/^\s*<[A-Z][\w.]*(?:\s|>|\/)/.test(source)) {
+        return;
+      }
+
+      properties[SYNTHETIC_FRAGMENT] = true;
+      node.properties = properties;
+      node.children = [{ type: 'text', value: `<>\n${source}\n</>` }];
+    });
+  };
+}
+
+function boundaryText(node: MdNode, fromEnd = false): MdNode | undefined {
+  if (node.type === 'text' && typeof node.value === 'string') {
+    return node;
+  }
+
+  const children = fromEnd ? [...(node.children || [])].reverse() : node.children || [];
+  for (const child of children) {
+    const match = boundaryText(child, fromEnd);
+    if (match) {
+      return match;
+    }
+  }
+
+  return undefined;
+}
+
+function rehypeRemoveHighlightingFragments() {
+  return (tree: MdNode) => {
+    walkTree(tree, node => {
+      if (node.tagName !== 'code') {
+        return;
+      }
+
+      const properties = (node.properties || {}) as Record<string, unknown>;
+      if (!properties[SYNTHETIC_FRAGMENT]) {
+        return;
+      }
+
+      const first = boundaryText(node);
+      const last = boundaryText(node, true);
+      if (first?.value) {
+        first.value = first.value.replace(/^<>\r?\n/, '');
+      }
+      if (last?.value) {
+        last.value = last.value.replace(/\r?\n<\/>$/, '');
+      }
+
+      delete properties[SYNTHETIC_FRAGMENT];
+    });
+  };
+}
+
+/**
+ * The MDX compilation pipeline, shared by the app build and the test runner so
+ * tests exercise the same transforms the site ships with.
+ */
+export function shisoMdx(): Plugin {
+  return {
+    // Must run before vite:react-babel so MDX is compiled to JSX first.
+    enforce: 'pre',
+    ...mdx({
+      providerImportSource: '@mdx-js/react',
+      remarkPlugins: [
+        remarkFrontmatter,
+        remarkMdxFrontmatter,
+        remarkGfm,
+        remarkCodeTitles,
+        remarkToc,
+      ],
+      rehypePlugins: [
+        rehypeWrapJsxForHighlighting,
+        rehypeHighlight,
+        rehypeRemoveHighlightingFragments,
+        rehypeSlug,
+        [
+          // Must follow rehypeSlug: the anchor href points at the id it sets.
+          rehypeAutolinkHeadings,
+          {
+            behavior: 'append',
+            // A per-heading label keeps the permalink keyboard-reachable and
+            // distinguishable, rather than aria-hidden and mouse-only.
+            properties: (node: MdNode) => ({
+              className: 'heading-anchor',
+              'aria-label': `Permalink to “${toText(node)}”`,
+            }),
+            content: { type: 'text', value: '#' },
+          },
+        ],
+      ],
+    }),
+  } as Plugin;
+}

package/package.json

@@ -1,103 +1,93 @@
 {
   "name": "@umami/shiso",
-  "version": "0.54.0",
-  "description": "A content layer for Next.js",
-  "homepage": "https://shiso.umami.is",
+  "version": "0.61.0",
+  "description": "Open-source documentation framework for Markdown and MDX sites.",
+  "type": "module",
+  "bin": {
+    "shiso": "./bin/shiso.mjs"
+  },
+  "exports": {
+    "./client": {
+      "types": "./types/client.d.ts",
+      "default": "./src/entry-client.tsx"
+    },
+    "./search": {
+      "types": "./types/search.d.ts",
+      "default": "./src/lib/search/provider.ts"
+    },
+    "./schema": "./docs.schema.json",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "scripts",
+    "src",
+    "types",
+    "docs.schema.json",
+    "mdx.config.ts",
+    "vite.config.ts",
+    "CHANGELOG.md",
+    "README.md"
+  ],
+  "scripts": {
+    "prepack": "pnpm test:package",
+    "test:package": "node scripts/check-package.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/umami-software/shiso.git"
+    "url": "https://github.com/umami-software/shiso.git",
+    "directory": "packages/shiso"
   },
-  "main": "dist/index.js",
-  "module": "dist/index.mjs",
-  "types": "dist/index.d.ts",
-  "files": [
-    "dist",
-    "server",
-    "styles.css"
+  "homepage": "https://shiso.umami.is",
+  "keywords": [
+    "shiso",
+    "documentation",
+    "docs",
+    "mdx",
+    "vite"
   ],
+  "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "dev": "next dev --port 8001 --turbo",
-    "build": "next build",
-    "start": "next start",
-    "lint": "next lint",
-    "icons": "svgr ./src/assets --out-dir src/components/svg --typescript",
-    "components": "tsc -p tsconfig.components.json",
-    "server": "tsc -p tsconfig.server.json",
-    "esbuild": "node esbuild.mjs",
-    "dts": "node dts.mjs",
-    "css": "node css.mjs",
-    "bundle": "npm-run-all components server dts esbuild css"
-  },
-  "lint-staged": {
-    "**/*.{js,jsx,ts,tsx}": [
-      "prettier --write",
-      "eslint"
-    ],
-    "**/*.css": [
-      "stylelint --fix",
-      "prettier --write"
-    ],
-    "**/*.json": [
-      "prettier --write"
-    ]
-  },
   "dependencies": {
+    "@base-ui/react": "^1.7.0",
     "@fontsource/inter": "^5.2.5",
     "@fontsource/jetbrains-mono": "^5.2.5",
-    "@mdx-js/loader": "^3.0.0",
-    "@mdx-js/mdx": "^3.1.0",
-    "@mdx-js/react": "^3.0.0",
-    "@umami/react-zen": "^0.89.0",
+    "@mdx-js/react": "^3.1.1",
+    "@mdx-js/rollup": "^3.1.1",
+    "@tailwindcss/vite": "^4.3.3",
+    "@vitejs/plugin-react": "^6.0.5",
+    "ajv": "^8.20.0",
+    "class-variance-authority": "^0.7.1",
     "classnames": "^2.5.1",
-    "date-fns": "^4.1.0",
-    "glob": "^10.3.10",
-    "gray-matter": "^4.0.3",
+    "clsx": "^2.1.1",
+    "cmdk": "^1.1.1",
+    "estree-util-value-to-estree": "^3.5.0",
+    "github-slugger": "^2.0.0",
     "highlight.js": "^11.11.1",
-    "next": "15.2.1",
-    "next-mdx-remote": "^5.0.0",
-    "react": "^19.1.0",
-    "react-dom": "^19.1.0",
-    "recursive-readdir": "^2.2.3",
+    "lucide-react": "^1.28.0",
+    "react-router": "^8.3.0",
+    "rehype-autolink-headings": "^7.1.0",
     "rehype-highlight": "^7.0.1",
     "rehype-slug": "^6.0.0",
-    "remark-gfm": "^4.0.0",
-    "thenby": "^1.3.4"
-  },
-  "devDependencies": {
-    "@svgr/cli": "^8.1.0",
-    "@types/css-modules": "^1.0.5",
-    "@types/mdx": "^2.0.11",
-    "@types/node": "^22.15.3",
-    "@types/react": "^19.1.2",
-    "@types/react-dom": "^19.1.3",
-    "@umami/esbuild-plugin-css-modules": "^0.4.0",
-    "dts-bundle": "^0.7.3",
-    "esbuild": "^0.25.3",
-    "esbuild-plugin-css-modules": "^0.3.0",
-    "eslint": "^9.25.1",
-    "eslint-config-next": "15.1.3",
-    "eslint-config-prettier": "^9.1.0",
-    "eslint-import-resolver-alias": "^1.1.2",
-    "eslint-plugin-import": "^2.29.1",
-    "eslint-plugin-prettier": "^5.2.6",
-    "husky": "^9.1.1",
-    "lint-staged": "^15.5.1",
-    "npm-run-all": "^4.1.5",
-    "prettier": "^3.2.5",
     "remark-frontmatter": "^5.0.0",
-    "remark-mdx-frontmatter": "^5.1.0",
-    "stylelint": "^15.10.1",
-    "stylelint-config-prettier": "^9.0.5",
-    "stylelint-config-recommended": "^14.0.1",
-    "typescript": "^5.8.3"
+    "remark-gfm": "^4.0.0",
+    "remark-mdx": "^3.1.1",
+    "remark-mdx-frontmatter": "^5.2.0",
+    "remark-parse": "^11.0.0",
+    "simple-icons": "^16.28.0",
+    "tailwind-merge": "^3.6.0",
+    "tailwindcss": "^4.3.3",
+    "tw-animate-css": "^1.4.0",
+    "unified": "^11.0.5",
+    "vite": "^8.2.0"
   },
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "esbuild",
-      "sharp"
-    ]
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
   }
 }

package/scripts/check-package.mjs

@@ -0,0 +1,18 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const root = path.resolve(import.meta.dirname, '..');
+
+for (const relativeFile of [
+  'bin/shiso.mjs',
+  'docs.schema.json',
+  'src/entry-client.tsx',
+  'src/entry-server.tsx',
+  'types/client.d.ts',
+  'types/search.d.ts',
+  'vite.config.ts',
+]) {
+  await fs.access(path.join(root, relativeFile));
+}
+
+console.log('shiso package contents are ready.');

package/scripts/generate-icon-registry.mjs

@@ -0,0 +1,196 @@
+/**
+ * Generates the project-local .shiso/icon-registry.generated.ts cache.
+ *
+ * Authors reference icons by name in MDX (`<Card icon="rocket">`). Importing all of
+ * lucide-react to support that would pull in ~4000 modules, so instead we scan the
+ * source for the icon names actually used and emit explicit named imports. The result
+ * tree-shakes normally and renders synchronously during prerender.
+ *
+ * Run via `pnpm icons:registry`, or automatically by the Vite plugin in vite.config.ts.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import * as lucide from 'lucide-react';
+import { loadDocsConfig } from './load-docs-config.mjs';
+
+const DEFAULT_ROOT = process.cwd();
+const SCAN_DIRS = ['content', 'src'];
+const SCAN_EXTENSIONS = new Set(['.md', '.mdx', '.tsx']);
+
+// Icons used by the docs component library itself, so pages always have a baseline set.
+const ALWAYS_INCLUDE = ['rocket', 'code', 'book-open', 'circle-check', 'circle-alert'];
+
+const ICON_ATTRIBUTE = /\bicon\s*=\s*["']([^"'{}\n]+)["']/g;
+
+// docs.json declares icons as JSON properties rather than JSX/MDX attributes.
+const ICON_JSON_PROPERTY = /"icon"\s*:\s*"([^"]+)"/g;
+const NON_LUCIDE_ICONS = new Set([
+  'bluesky',
+  'discord',
+  'facebook',
+  'github',
+  'hacker-news',
+  'instagram',
+  'linkedin',
+  'medium',
+  'reddit',
+  'slack',
+  'telegram',
+  'threads',
+  'twitter',
+  'x',
+  'x-twitter',
+  'youtube',
+]);
+
+/** `circle-check`, `circle_check`, `CircleCheck` -> `circle-check` */
+export function normalizeIconName(name) {
+  return name
+    .trim()
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/[\s_]+/g, '-')
+    .toLowerCase()
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+/** `circle-check` -> `CircleCheck` */
+function toPascalCase(name) {
+  return name
+    .split('-')
+    .filter(Boolean)
+    .map(part => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('');
+}
+
+async function collectFiles(dir, files = []) {
+  let entries;
+
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return files;
+  }
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      if (entry.name === 'node_modules' || entry.name.startsWith('.')) {
+        continue;
+      }
+      await collectFiles(fullPath, files);
+    } else if (SCAN_EXTENSIONS.has(path.extname(entry.name))) {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}
+
+function addMatches(names, source, pattern) {
+  for (const match of source.matchAll(pattern)) {
+    const value = match[1].trim();
+
+    if (
+      /^(?:https?:|data:image\/|\/|\.\.?\/)/i.test(value) ||
+      /\.(?:avif|gif|jpe?g|png|svg|webp)(?:[?#].*)?$/i.test(value)
+    ) {
+      continue;
+    }
+
+    const normalized = normalizeIconName(value);
+
+    if (normalized && /^[a-z0-9-]+$/.test(normalized)) {
+      names.add(normalized);
+    }
+  }
+}
+
+async function findIconNames(config, root) {
+  const names = new Set(ALWAYS_INCLUDE);
+
+  for (const dir of SCAN_DIRS) {
+    const files = await collectFiles(path.join(root, dir));
+
+    for (const file of files) {
+      addMatches(names, await fs.readFile(file, 'utf8'), ICON_ATTRIBUTE);
+    }
+  }
+
+  // Navigation and navbar icons live in docs.json, not in content or source.
+  const docsConfig = config ?? (await loadDocsConfig({ root })).config;
+  addMatches(names, JSON.stringify(docsConfig), ICON_JSON_PROPERTY);
+
+  return [...names].sort();
+}
+
+function renderModule(entries) {
+  const imports = entries.map(({ component }) => `  ${component},`).join('\n');
+  const mapping = entries
+    .map(({ name, component }) => {
+      // Match the formatter's "quote props as needed" style.
+      const key = /^[A-Za-z_$][\w$]*$/.test(name) ? name : `'${name}'`;
+
+      return `  ${key}: ${component},`;
+    })
+    .join('\n');
+
+  return `// Generated by scripts/generate-icon-registry.mjs. Do not edit by hand.
+// Add icons by using them in content (\`icon="name"\`) and rebuilding.
+import {
+${imports}
+} from 'lucide-react';
+import type { IconComponent } from '@/lib/icons';
+
+export const ICON_REGISTRY: Record<string, IconComponent> = {
+${mapping}
+};
+`;
+}
+
+/** @param {{ config?: object, root?: string, output?: string }} [options] */
+export async function generateIconRegistry({
+  config,
+  root = DEFAULT_ROOT,
+  output = path.join(root, '.shiso/icon-registry.generated.ts'),
+} = {}) {
+  const names = await findIconNames(config, root);
+  const entries = [];
+  const unknown = [];
+
+  for (const name of names) {
+    if (NON_LUCIDE_ICONS.has(name)) {
+      continue;
+    }
+
+    const component = toPascalCase(name);
+
+    if (component in lucide) {
+      entries.push({ name, component });
+    } else {
+      unknown.push(name);
+    }
+  }
+
+  const contents = renderModule(entries);
+  const previous = await fs.readFile(output, 'utf8').catch(() => '');
+
+  if (previous !== contents) {
+    await fs.mkdir(path.dirname(output), { recursive: true });
+    await fs.writeFile(output, contents);
+  }
+
+  return { count: entries.length, unknown, changed: previous !== contents };
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  const { count, unknown } = await generateIconRegistry();
+
+  console.log(`Icon registry: ${count} icons`);
+
+  if (unknown.length) {
+    console.warn(`Unknown icon names (not in lucide): ${unknown.join(', ')}`);
+  }
+}

package/scripts/generate-last-modified.mjs

@@ -0,0 +1,128 @@
+/**
+ * Generates the project-local .shiso/last-modified.ts cache.
+ *
+ * The `metadata.timestamp` config key shows a last-modified date on pages.
+ * That date comes from git history, which only exists at build time, so a
+ * single `git log` pass over the repo maps every content file to the date of
+ * the latest commit that touched it. Files not committed yet fall back to
+ * filesystem mtime.
+ *
+ * Run via `pnpm timestamps`, or automatically by the Vite plugin exported below.
+ */
+import { execFile } from 'node:child_process';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+const DEFAULT_ROOT = process.cwd();
+const CONTENT_EXTENSIONS = new Set(['.md', '.mdx']);
+
+async function collectContentFiles(dir, files = []) {
+  let entries;
+
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return files;
+  }
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      await collectContentFiles(fullPath, files);
+    } else if (CONTENT_EXTENSIONS.has(path.extname(entry.name))) {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}
+
+/** Latest commit date per repo path, from one newest-first `git log` pass. */
+async function getGitDates(root) {
+  const dates = new Map();
+
+  try {
+    const { stdout } = await execFileAsync(
+      'git',
+      ['-c', 'core.quotePath=false', 'log', '--format=@%cI', '--name-only', '--', 'content'],
+      { cwd: root, maxBuffer: 64 * 1024 * 1024 },
+    );
+
+    let current = '';
+
+    for (const line of stdout.split('\n')) {
+      if (line.startsWith('@')) {
+        current = line.slice(1).trim();
+      } else if (line.trim() && current && !dates.has(line.trim())) {
+        dates.set(line.trim(), current);
+      }
+    }
+  } catch {
+    // Not a git checkout (e.g. a tarball build); every file uses mtime.
+  }
+
+  return dates;
+}
+
+export async function generateLastModified({
+  root = DEFAULT_ROOT,
+  output = path.join(root, '.shiso/last-modified.ts'),
+} = {}) {
+  const files = await collectContentFiles(path.join(root, 'content'));
+  const gitDates = await getGitDates(root);
+  const entries = [];
+
+  for (const file of files.sort()) {
+    const repoPath = path.relative(root, file).split(path.sep).join('/');
+    let date = gitDates.get(repoPath);
+
+    if (!date) {
+      const stat = await fs.stat(file);
+      date = stat.mtime.toISOString();
+    }
+
+    // Module keys as produced by import.meta.glob: "/content/docs/index.mdx".
+    entries.push([`/${repoPath}`, date]);
+  }
+
+  const mapping = entries.map(([key, date]) => `  '${key}': '${date}',`).join('\n');
+  const contents = `// Generated by scripts/generate-last-modified.mjs. Do not edit by hand.
+export const LAST_MODIFIED: Record<string, string> = {
+${mapping}
+};
+`;
+
+  const previous = await fs.readFile(output, 'utf8').catch(() => '');
+
+  if (previous !== contents) {
+    await fs.mkdir(path.dirname(output), { recursive: true });
+    await fs.writeFile(output, contents);
+  }
+
+  return { count: entries.length, changed: previous !== contents };
+}
+
+/** Ensures consumers can import the generated module before Vite loads app code. */
+export function shisoLastModified(options = {}) {
+  return {
+    name: 'shiso-last-modified',
+    async buildStart() {
+      await generateLastModified(options);
+    },
+    async handleHotUpdate({ file }) {
+      if (/\.(md|mdx)$/.test(file)) {
+        await generateLastModified(options);
+      }
+    },
+  };
+}
+
+if (process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url) {
+  const { count } = await generateLastModified();
+  console.log(`Last-modified dates: ${count} files`);
+}