Core: Deprecate fumadocs-core/server

.changeset/lazy-items-yawn.md

@@ -0,0 +1,15 @@
+---
+'fumadocs-core': patch
+---
+
+**Deprecate `fumadocs-core/server` export**
+
+It will be removed on Fumadocs 16, as some APIs under the `/server` export are actually available (and even used) under browser environment.
+
+A more modularized design will be introduced over the original naming. 
+
+- **`getGithubLastEdit`:** Moved to `fumadocs-core/content/github`.
+- **`getTableOfContents`:** Moved to `fumadocs-core/content/toc`.
+- **`PageTree` and page tree utilities:** Moved to `fumadocs-core/page-tree`.
+- **`TOCItemType`, `TableOfContents`:** Moved to `fumadocs-core/toc`.
+- **`createMetadataImage`:** Deprecated, use the Next.js Metadata API instead.

packages/core/package.json

@@ -1,9 +1,9 @@
 {
   "name": "fumadocs-core",
   "version": "15.8.1",
-  "description": "The library for building a documentation website in Next.js",
+  "description": "The library for building a documentation website in any React.js framework",
   "keywords": [
-    "NextJs",
+    "Fumadocs",
     "Docs"
   ],
   "homepage": "https://fumadocs.dev",
@@ -28,6 +28,10 @@
       "import": "./dist/content/index.js",
       "types": "./dist/content/index.d.ts"
     },
+    "./content/*": {
+      "import": "./dist/content/*.js",
+      "types": "./dist/content/*.d.ts"
+    },
     "./hide-if-empty": {
       "import": "./dist/hide-if-empty.js",
       "types": "./dist/hide-if-empty.d.ts"
@@ -36,6 +40,10 @@
       "import": "./dist/negotiation/index.js",
       "types": "./dist/negotiation/index.d.ts"
     },
+    "./page-tree": {
+      "import": "./dist/page-tree/index.js",
+      "types": "./dist/page-tree/index.d.ts"
+    },
     "./search": {
       "import": "./dist/search/index.js",
       "types": "./dist/search/index.d.ts"

packages/core/src/breadcrumb.tsx

@@ -1,7 +1,7 @@
 import { type ReactNode, useMemo } from 'react';
-import type * as PageTree from '@/source/page-tree/definitions';
+import type * as PageTree from '@/page-tree/definitions';
 import { normalizeUrl } from '@/utils/normalize-url';
-import { findPath } from '@/utils/page-tree';
+import { findPath } from '@/page-tree/utils';
 
 export interface BreadcrumbItem {
   name: ReactNode;

packages/core/src/content/toc.ts

@@ -1,23 +1,15 @@
 import { remark } from 'remark';
-import type { ReactNode } from 'react';
 import { remarkHeading } from '@/mdx-plugins/remark-heading';
 import type { PluggableList } from 'unified';
 import type { Compatible } from 'vfile';
-
-export interface TOCItemType {
-  title: ReactNode;
-  url: string;
-  depth: number;
-}
-
-export type TableOfContents = TOCItemType[];
+import type { TOCItemType } from '@/toc';
 
 /**
  * Get Table of Contents from markdown/mdx document (using remark)
  *
  * @param content - Markdown content or file
  */
-export function getTableOfContents(content: Compatible): TableOfContents;
+export function getTableOfContents(content: Compatible): TOCItemType[];
 
 /**
  * Get Table of Contents from markdown/mdx document (using remark)
@@ -28,28 +20,27 @@ export function getTableOfContents(content: Compatible): TableOfContents;
 export function getTableOfContents(
   content: Compatible,
   remarkPlugins: PluggableList,
-): Promise<TableOfContents>;
+): Promise<TOCItemType[]>;
 
 export function getTableOfContents(
   content: Compatible,
   remarkPlugins?: PluggableList,
-): TableOfContents | Promise<TableOfContents> {
+): TOCItemType[] | Promise<TOCItemType[]> {
   if (remarkPlugins) {
     return remark()
       .use(remarkPlugins)
       .use(remarkHeading)
       .process(content)
       .then((result) => {
-        if ('toc' in result.data) return result.data.toc as TableOfContents;
+        if ('toc' in result.data) return result.data.toc as TOCItemType[];
 
         return [];
       });
   }
 
-  // compatible with previous versions
+  // compatible with sync usages
   const result = remark().use(remarkHeading).processSync(content);
 
-  if ('toc' in result.data) return result.data.toc as TableOfContents;
-
+  if ('toc' in result.data) return result.data.toc as TOCItemType[];
   return [];
 }

packages/core/src/page-tree/index.ts

@@ -0,0 +1,2 @@
+export * from './definitions';
+export * from './utils';

packages/core/src/page-tree/utils.ts

@@ -1,4 +1,4 @@
-import type * as PageTree from '@/source/page-tree/definitions';
+import type * as PageTree from '@/page-tree/definitions';
 
 /**
  * Flatten tree to an array of page nodes
@@ -64,23 +64,6 @@ export function getPageTreeRoots(
   return result;
 }
 
-/**
- * Separate the folder nodes of a root into multiple roots
- *
- * @deprecated it's useless
- */
-export function separatePageTree(pageTree: PageTree.Root): PageTree.Root[] {
-  return pageTree.children.flatMap((child) => {
-    if (child.type !== 'folder') return [];
-
-    return {
-      name: child.name,
-      url: child.index?.url,
-      children: child.children,
-    };
-  });
-}
-
 /**
  * Get other page tree nodes that lives under the same parent
  */

packages/core/src/search/orama/create-from-source.ts

@@ -15,7 +15,7 @@ import { type StructuredData } from '@/mdx-plugins';
 import { basename, extname } from '@/source/path';
 import type { I18nConfig } from '@/i18n';
 import type { Language } from '@orama/orama';
-import { findPath } from '@/utils/page-tree';
+import { findPath } from '@/page-tree/utils';
 
 type Awaitable<T> = T | Promise<T>;
 

packages/core/src/server/index.ts

@@ -1,8 +1,18 @@
-export * from './get-toc';
-export * from '../utils/page-tree';
-export * as PageTree from '../source/page-tree/definitions';
-export * from './git-api';
+// TODO: replace this with `fumadocs-core/content/github`
+export * from '@/content/github';
+
+// removed on next major
 export * from './metadata';
 
+// TODO: replace this with 'fumadocs-core/content/toc'
+export * from '@/content/toc';
+
+// TODO: replace this with 'fumadocs-core/toc'
+export type { TOCItemType, TableOfContents } from '@/toc';
+
 // TODO: replace this with `fumadocs-core/search`
 export type { SortedResult } from '../search';
+
+// TODO: replace this with `fumadocs-core/page-tree`
+export * from '@/page-tree/utils';
+export type * as PageTree from '@/page-tree/definitions';

packages/core/src/server/metadata.ts

@@ -13,6 +13,9 @@ interface ImageMeta {
   height: number;
 }
 
+/**
+ * @deprecated Use the SEO features of your own React.js framework instead
+ */
 export function createMetadataImage<
   S extends LoaderOutput<LoaderConfig>,
 >(options: {

packages/core/src/source/index.ts

@@ -4,7 +4,7 @@ export {
   type PageTreeBuilder,
   type PageTreeBuilderContext,
   type BaseOptions,
-} from './page-tree/builder';
+} from '@/source/page-tree/builder';
 export * from './loader';
 export { FileSystem } from './file-system';
 
@@ -17,10 +17,5 @@ export {
   type Transformer,
 } from './load-files';
 export type * from './types';
-export {
-  type FileInfo,
-  type FolderInfo,
-  parseFilePath,
-  parseFolderPath,
-} from './path';
+export { type FileInfo, type FolderInfo, parseFilePath } from './path';
 export type * from './plugins';

packages/core/src/source/loader.ts

@@ -1,4 +1,4 @@
-import type * as PageTree from '@/source/page-tree/definitions';
+import type * as PageTree from '@/page-tree/definitions';
 import type { I18nConfig } from '@/i18n';
 import {
   type ContentStorage,
@@ -7,7 +7,10 @@ import {
   type PageFile,
 } from './load-files';
 import type { MetaData, PageData, UrlFn } from './types';
-import { type BaseOptions, createPageTreeBuilder } from './page-tree/builder';
+import {
+  type BaseOptions,
+  createPageTreeBuilder,
+} from '@/source/page-tree/builder';
 import {
   basename,
   dirname,

packages/core/src/source/page-tree/builder.ts

@@ -1,5 +1,5 @@
-import type * as PageTree from './definitions';
-import type { MetaData, PageData, UrlFn } from '../types';
+import type * as PageTree from '@/page-tree/definitions';
+import type { MetaData, PageData, UrlFn } from '@/source';
 import type { ContentStorage } from '@/source/load-files';
 import { basename, extname, joinPath } from '@/source/path';
 import { transformerFallback } from '@/source/page-tree/transformer-fallback';

packages/core/src/source/path.ts

@@ -79,17 +79,6 @@ export function parseFilePath(path: string): FileInfo {
   };
 }
 
-/**
- * @deprecated use `dirname` and `basename` directly.
- */
-export function parseFolderPath(path: string): FolderInfo {
-  return {
-    dirname: dirname(path),
-    name: basename(path),
-    path,
-  };
-}
-
 /**
  * Split path into segments, trailing/leading slashes are removed
  */

packages/core/src/source/plugins/compat.ts

@@ -6,7 +6,7 @@ import type {
   PageTreeTransformer,
   Transformer,
 } from '@/source';
-import type * as PageTree from '../page-tree/definitions';
+import type * as PageTree from '@/page-tree/definitions';
 import type { LoaderPlugin } from '@/source/plugins';
 
 export interface LegacyLoaderOptions {

packages/core/src/source/plugins/icon.ts

@@ -1,6 +1,6 @@
 import type { LoaderPlugin } from '@/source';
 import type { ReactNode } from 'react';
-import type * as PageTree from '@/source/page-tree/definitions';
+import type * as PageTree from '@/page-tree/definitions';
 
 export type IconResolver = (icon: string | undefined) => ReactNode;
 

packages/core/src/toc.tsx

@@ -2,11 +2,18 @@
 import type { AnchorHTMLAttributes, ReactNode, RefObject } from 'react';
 import { createContext, forwardRef, useContext, useMemo, useRef } from 'react';
 import scrollIntoView from 'scroll-into-view-if-needed';
-import type { TableOfContents } from '@/server/get-toc';
 import { mergeRefs } from '@/utils/merge-refs';
 import { useOnChange } from '@/utils/use-on-change';
 import { useAnchorObserver } from './utils/use-anchor-observer';
 
+export interface TOCItemType {
+  title: ReactNode;
+  url: string;
+  depth: number;
+}
+
+export type TableOfContents = TOCItemType[];
+
 const ActiveAnchorContext = createContext<string[]>([]);
 
 const ScrollContext = createContext<RefObject<HTMLElement | null>>({

packages/core/test/index.test.ts

@@ -1,13 +1,7 @@
-import {
-  joinPath,
-  parseFilePath,
-  parseFolderPath,
-  splitPath,
-} from '@/source/path';
+import { joinPath, parseFilePath, splitPath } from '@/source/path';
 import { describe, expect, test } from 'vitest';
-import type { Root } from '@/source/page-tree/definitions';
-import { findNeighbour } from '@/utils/page-tree';
-import { PageTree } from '../dist/server';
+import type { Root } from '@/page-tree/definitions';
+import { findNeighbour } from '@/page-tree/utils';
 import { getBreadcrumbItems } from '@/breadcrumb';
 
 test('Find Neighbours', () => {
@@ -83,24 +77,6 @@ describe('Path utilities', () => {
     `);
   });
 
-  test('parse folder path', () => {
-    expect(parseFolderPath('')).toMatchInlineSnapshot(`
-      {
-        "dirname": "",
-        "name": "",
-        "path": "",
-      }
-    `);
-
-    expect(parseFolderPath('nested/nested')).toMatchInlineSnapshot(`
-      {
-        "dirname": "nested",
-        "name": "nested",
-        "path": "nested/nested",
-      }
-    `);
-  });
-
   test('resolve paths', () => {
     expect(joinPath('a', 'b')).toBe('a/b');
     expect(joinPath('/a', '')).toBe('a');
@@ -118,7 +94,7 @@ describe('Path utilities', () => {
 });
 
 test('Breadcrumbs', () => {
-  const tree: PageTree.Root = {
+  const tree: Root = {
     name: 'Hello World',
     children: [
       {

packages/core/tsup.config.ts

@@ -11,8 +11,9 @@ export default defineConfig({
   format: 'esm',
   entry: [
     'src/{toc,link,breadcrumb,sidebar,dynamic-link,hide-if-empty}.tsx',
-    'src/{server,source,mdx-plugins,content}/index.ts',
+    'src/{server,source,mdx-plugins,page-tree}/index.ts',
     'src/negotiation/*.ts',
+    'src/content/*.ts',
     'src/search/{index,client,server,algolia,orama-cloud}.ts',
     'src/utils/use-on-change.ts',
     'src/utils/use-effect-event.ts',