@vezham/docs-core 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Fuma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+# Fumadocs Core
+
+The core library for Fumadocs.
+
+📘 Learn More: [Documentation](https://fumadocs.dev)

package/dist/advanced-Ct13khZr.js

@@ -0,0 +1,79 @@
+import { createContentHighlighter } from "./search/index.js";
+import { t as removeUndefined } from "./remove-undefined-CzMSKybq.js";
+import { getByID, search } from "zbsearch";
+//#region src/search/zbsearch/search/simple.ts
+async function searchSimple(db, query, params = {}, locale) {
+	const highlighter = createContentHighlighter(query);
+	return (await search(db, {
+		term: query,
+		tolerance: 1,
+		...params,
+		boost: {
+			title: 2,
+			..."boost" in params ? params.boost : void 0
+		},
+		where: removeUndefined({
+			locale: locale ? { eq: locale } : void 0,
+			...params.where
+		})
+	})).hits.map((hit) => ({
+		type: "page",
+		content: highlighter.highlightMarkdown(hit.document.title),
+		breadcrumbs: hit.document.breadcrumbs,
+		id: hit.document.url,
+		url: hit.document.url
+	}));
+}
+//#endregion
+//#region src/search/zbsearch/search/advanced.ts
+async function searchAdvanced(db, query, tag = [], { mode = "fulltext", ...override } = {}, locale) {
+	if (typeof tag === "string") tag = [tag];
+	const params = {
+		limit: 60,
+		mode,
+		...override,
+		where: removeUndefined({
+			tags: tag.length > 0 ? { containsAll: tag } : void 0,
+			locale: locale ? { eq: locale } : void 0,
+			...override.where
+		}),
+		groupBy: {
+			properties: ["page_id"],
+			maxResult: 8,
+			...override.groupBy
+		},
+		properties: mode === "fulltext" ? ["content"] : ["content", "embeddings"]
+	};
+	if (query.length > 0) params.term = query;
+	const highlighter = createContentHighlighter(query);
+	const result = await search(db, params);
+	const limit = typeof params.limit === "number" ? params.limit : Infinity;
+	const list = [];
+	for (const item of result.groups ?? []) {
+		if (list.length >= limit) break;
+		const pageId = item.values[0];
+		const page = getByID(db, pageId);
+		if (!page) continue;
+		list.push({
+			id: pageId,
+			type: "page",
+			content: highlighter.highlightMarkdown(page.content),
+			breadcrumbs: page.breadcrumbs,
+			url: page.url
+		});
+		for (const hit of item.result) {
+			if (list.length >= limit) break;
+			if (hit.document.type === "page") continue;
+			list.push({
+				id: hit.document.id.toString(),
+				content: highlighter.highlightMarkdown(hit.document.content),
+				breadcrumbs: hit.document.breadcrumbs,
+				type: hit.document.type,
+				url: hit.document.url
+			});
+		}
+	}
+	return list;
+}
+//#endregion
+export { searchSimple as n, searchAdvanced as t };

package/dist/algolia-C0E5qQhM.d.ts

@@ -0,0 +1,66 @@
+import { i as StructuredData } from "./remark-structure-CnHwvNZr.js";
+import { Algoliasearch } from "algoliasearch";
+//#region src/search/algolia.d.ts
+interface DocumentRecord {
+  /**
+   * The ID of document, must be unique
+   */
+  _id: string;
+  title: string;
+  description?: string;
+  breadcrumbs?: string[];
+  /**
+   * URL to the page
+   */
+  url: string;
+  structured: StructuredData;
+  /**
+   * Tag to filter results
+   */
+  tag?: string;
+  /**
+   * Data to be added to each section index
+   */
+  extra_data?: object;
+}
+interface SyncOptions {
+  /**
+   * Index Name for documents.
+   */
+  indexName?: string;
+  /**
+   * Search indexes
+   */
+  documents: DocumentRecord[];
+}
+/**
+ * Update index settings and replace all objects
+ *
+ * @param client - Algolia Admin Client
+ * @param options - Index Options
+ */
+declare function sync(client: Algoliasearch, options: SyncOptions): Promise<void>;
+declare function setIndexSettings(client: Algoliasearch, indexName: string): Promise<void>;
+declare function updateDocuments(client: Algoliasearch, indexName: string, documents: DocumentRecord[]): Promise<void>;
+interface BaseIndex {
+  objectID: string;
+  title: string;
+  url: string;
+  tag?: string;
+  /**
+   * The id of page, used for distinct
+   */
+  page_id: string;
+  /**
+   * Heading content
+   */
+  section?: string;
+  /**
+   * Heading (anchor) id
+   */
+  section_id?: string;
+  breadcrumbs?: string[];
+  content: string;
+}
+//#endregion
+export { sync as a, setIndexSettings as i, DocumentRecord as n, updateDocuments as o, SyncOptions as r, BaseIndex as t };

package/dist/breadcrumb.d.ts

@@ -0,0 +1,46 @@
+import { i as Root, r as Node, t as Folder } from "./definitions-CFOhwE1k.js";
+import { ReactNode } from "react";
+//#region src/breadcrumb.d.ts
+interface BreadcrumbItem {
+  name: ReactNode;
+  url?: string;
+}
+interface BreadcrumbOptions {
+  /**
+   * Include the root folders in the breadcrumb items array.
+   *
+   * @defaultValue false
+   */
+  includeRoot?: boolean | {
+    /**
+     * Specify the url of root
+     */
+    url: string;
+  };
+  /**
+   * Include the page itself in the breadcrumb items array
+   *
+   * @defaultValue false
+   */
+  includePage?: boolean;
+  /**
+   * Count separator as an item
+   *
+   * @defaultValue false
+   */
+  includeSeparator?: boolean;
+}
+declare function useBreadcrumb(url: string, tree: Root | Folder, options?: BreadcrumbOptions): BreadcrumbItem[];
+declare function getBreadcrumbItems(url: string, tree: Root | Folder, options?: BreadcrumbOptions): BreadcrumbItem[];
+declare function getBreadcrumbItemsFromPath(tree: Root | Folder, path: Node[], options: BreadcrumbOptions): BreadcrumbItem[];
+/**
+ * Search the path of a node in the tree by a specified url
+ *
+ * - When the page doesn't exist, return null
+ *
+ * @returns The path to the target node from root
+ * @internal Don't use this on your own
+ */
+declare function searchPath(nodes: Node[], url: string): Node[] | null;
+//#endregion
+export { BreadcrumbItem, BreadcrumbOptions, getBreadcrumbItems, getBreadcrumbItemsFromPath, searchPath, useBreadcrumb };

package/dist/breadcrumb.js

@@ -0,0 +1,59 @@
+import { r as normalizeUrl } from "./url-BVHvi3_K.js";
+import { r as findPath } from "./utils-DEVq3cEC.js";
+import { useMemo } from "react";
+//#region src/breadcrumb.tsx
+function useBreadcrumb(url, tree, options) {
+	return useMemo(() => getBreadcrumbItems(url, tree, options), [
+		tree,
+		url,
+		options
+	]);
+}
+function getBreadcrumbItems(url, tree, options = {}) {
+	return getBreadcrumbItemsFromPath(tree, searchPath(tree.children, url) ?? [], options);
+}
+function getBreadcrumbItemsFromPath(tree, path, options) {
+	const { includePage = false, includeSeparator = false, includeRoot = false } = options;
+	let items = [];
+	for (let i = 0; i < path.length; i++) {
+		const item = path[i];
+		switch (item.type) {
+			case "page":
+				if (includePage) items.push({
+					name: item.name,
+					url: item.url
+				});
+				break;
+			case "folder":
+				if (item.root) {
+					items = [];
+					if (includeRoot) items.push({
+						name: tree.name,
+						url: typeof includeRoot === "object" ? includeRoot.url : item.index?.url
+					});
+					break;
+				}
+				if (i === path.length - 1 || item.index !== path[i + 1]) items.push({
+					name: item.name,
+					url: item.index?.url
+				});
+				break;
+			case "separator": if (item.name && includeSeparator) items.push({ name: item.name });
+		}
+	}
+	return items;
+}
+/**
+* Search the path of a node in the tree by a specified url
+*
+* - When the page doesn't exist, return null
+*
+* @returns The path to the target node from root
+* @internal Don't use this on your own
+*/
+function searchPath(nodes, url) {
+	const normalizedUrl = normalizeUrl(url);
+	return findPath(nodes, (node) => node.type === "page" && node.url === normalizedUrl);
+}
+//#endregion
+export { getBreadcrumbItems, getBreadcrumbItemsFromPath, searchPath, useBreadcrumb };

package/dist/build-doc-4OvfjVN2.js

@@ -0,0 +1,85 @@
+import { r as findPath } from "./utils-DEVq3cEC.js";
+import { r as extname, t as basename } from "./path-1H5VzYiT.js";
+//#region src/search/server/build-index.ts
+async function buildIndexDefault(page) {
+	let structuredData;
+	if (page.data.structuredData) structuredData = typeof page.data.structuredData === "function" ? await page.data.structuredData() : page.data.structuredData;
+	else if ("load" in page.data && typeof page.data.load === "function") structuredData = (await page.data.load()).structuredData;
+	if (!structuredData) throw new Error("Cannot find structured data from page, please define the page to index function.");
+	return {
+		title: page.data.title ?? basename(page.path, extname(page.path)),
+		description: page.data.description,
+		url: page.url,
+		id: page.url,
+		structuredData
+	};
+}
+function isBreadcrumbItem(item) {
+	return typeof item === "string" && item.length > 0;
+}
+function buildBreadcrumbs(source, page) {
+	const pageTree = source.getPageTree(page.locale);
+	const path = findPath(pageTree.children, (node) => node.type === "page" && node.url === page.url);
+	if (path) {
+		const breadcrumbs = [];
+		path.pop();
+		if (isBreadcrumbItem(pageTree.name)) breadcrumbs.push(pageTree.name);
+		for (const segment of path) {
+			if (!isBreadcrumbItem(segment.name)) continue;
+			breadcrumbs.push(segment.name);
+		}
+		return breadcrumbs;
+	}
+}
+//#endregion
+//#region src/search/server/build-doc.ts
+function buildDocuments(indexes) {
+	const docs = [];
+	for (const page of indexes) {
+		const pageTag = page.tag ?? [];
+		const tags = Array.isArray(pageTag) ? pageTag : [pageTag];
+		const data = page.structuredData;
+		let id = 0;
+		docs.push({
+			id: page.id,
+			page_id: page.id,
+			type: "page",
+			content: page.title,
+			breadcrumbs: page.breadcrumbs,
+			tags,
+			url: page.url,
+			locale: page.locale
+		});
+		const nextId = () => `${page.id}-${id++}`;
+		if (page.description && !data.contents.some((item) => item.content === page.description)) docs.push({
+			id: nextId(),
+			page_id: page.id,
+			tags,
+			type: "text",
+			url: page.url,
+			content: page.description,
+			locale: page.locale
+		});
+		for (const heading of data.headings) docs.push({
+			id: nextId(),
+			page_id: page.id,
+			type: "heading",
+			tags,
+			url: `${page.url}#${heading.id}`,
+			content: heading.content,
+			locale: page.locale
+		});
+		for (const content of data.contents) docs.push({
+			id: nextId(),
+			page_id: page.id,
+			tags,
+			type: "text",
+			url: content.heading ? `${page.url}#${content.heading}` : page.url,
+			content: content.content,
+			locale: page.locale
+		});
+	}
+	return docs;
+}
+//#endregion
+export { buildBreadcrumbs as n, buildIndexDefault as r, buildDocuments as t };

package/dist/client-kQ39Ub0-.d.ts

@@ -0,0 +1,247 @@
+import { t as Awaitable } from "./types-D89QoQR-.js";
+import { t as BaseIndex } from "./algolia-C0E5qQhM.js";
+import { r as SortedResult } from "./index-BM36H-xw.js";
+import { DependencyList } from "react";
+import { AnyZBSearch, SearchParams } from "zbsearch";
+import { LiteClient, SearchResponse } from "algoliasearch/lite";
+import { OramaCloud, OramaCloudSearchParams } from "@orama/core";
+import { ClientSearchParams, OramaClient } from "@oramacloud/client";
+import Mixedbread from "@mixedbread/sdk";
+//#region src/search/client/fetch.d.ts
+interface FetchOptions {
+  /**
+   * API route for search endpoint, support absolute URLs.
+   *
+   * @defaultValue '/api/search'
+   */
+  api?: string;
+  /**
+   * Filter results with specific tag(s).
+   */
+  tag?: string | string[];
+  /**
+   * Filter by locale
+   */
+  locale?: string;
+  cache?: Map<string, SortedResult[]>;
+}
+declare function fetchClient({ api, locale, tag, cache }?: FetchOptions): SearchClient;
+//#endregion
+//#region src/search/client/orama-static.d.ts
+interface StaticOptions {
+  /**
+   * Where to download exported search indexes (URL)
+   *
+   * @defaultValue '/api/search'
+   */
+  from?: string;
+  /**
+   * Customize how the search database is initialized (advanced).
+   *
+   * For legacy per-locale exports, it is called once per locale.
+   */
+  initDB?: (locale?: string) => AnyZBSearch | Promise<AnyZBSearch>;
+  /**
+   * @deprecated Renamed to `initDB`, note that the search engine is now ZBSearch.
+   */
+  initOrama?: (locale?: string) => AnyZBSearch | Promise<AnyZBSearch>;
+  /**
+   * Filter results with specific tag(s).
+   */
+  tag?: string | string[];
+  /**
+   * Filter by locale (for i18n)
+   */
+  locale?: string;
+  /**
+   * extra options for search
+   */
+  search?: Partial<SearchParams<AnyZBSearch>>;
+}
+declare function staticClient(options?: StaticOptions): SearchClient;
+/**
+ * @deprecated Renamed to `staticClient`, note that the search engine is now ZBSearch.
+ */
+declare const oramaStaticClient: typeof staticClient;
+//#endregion
+//#region src/search/client/algolia.d.ts
+interface AlgoliaOptions {
+  indexName: string;
+  client: LiteClient;
+  /**
+   * Filter results with specific tag.
+   */
+  tag?: string;
+  locale?: string;
+  onSearch?: (query: string, tag?: string, locale?: string) => Promise<{
+    results: SearchResponse<BaseIndex>[];
+  }>;
+}
+declare function algoliaClient(options: AlgoliaOptions): SearchClient;
+//#endregion
+//#region src/search/client/orama-cloud.d.ts
+interface OramaCloudOptions {
+  client: OramaCloud;
+  /**
+   * The type of your index.
+   *
+   * You can set it to `crawler` if you use crawler instead of the JSON index with schema provided by Fumadocs
+   */
+  index?: 'default' | 'crawler';
+  /**
+   * Note: not included in dependency list.
+   */
+  params?: Partial<OramaCloudSearchParams>;
+  /**
+   * Filter results with specific tag.
+   */
+  tag?: string;
+  /**
+   * Filter by locale (unsupported at the moment)
+   */
+  locale?: string;
+}
+declare function oramaCloudClient(options: OramaCloudOptions): SearchClient;
+//#endregion
+//#region src/search/client/orama-cloud-legacy.d.ts
+interface OramaCloudLegacyOptions {
+  client: OramaClient;
+  /**
+   * The type of your index.
+   *
+   * You can set it to `crawler` if you use crawler instead of the JSON index with schema provided by Fumadocs.
+   */
+  index?: 'default' | 'crawler';
+  /**
+   * Note: not included into dependency list.
+   */
+  params?: ClientSearchParams;
+  /**
+   * Filter results with specific tag.
+   */
+  tag?: string;
+  /**
+   * Filter by locale (unsupported at the moment)
+   */
+  locale?: string;
+}
+declare function oramaCloudLegacyClient(options: OramaCloudLegacyOptions): SearchClient;
+//#endregion
+//#region src/search/client/mixedbread.d.ts
+interface MixedbreadOptions {
+  /**
+   * The identifier of the store to search in
+   */
+  storeIdentifier: string;
+  /**
+   * The Mixedbread SDK client instance
+   */
+  client: Mixedbread;
+  /**
+   * Filter results with specific tag.
+   */
+  tag?: string;
+  /**
+   * Filter by locale (unsupported at the moment)
+   */
+  locale?: string;
+}
+interface SearchMetadata {
+  title?: string;
+  description?: string;
+  url?: string;
+  tag?: string;
+}
+/**
+ * @deprecated Use `createMixedbreadSearchAPI` from `@vezham/docs-core/search/mixedbread` instead.
+ * This client-side approach exposes your API key in the browser.
+ * The server-side approach keeps the key secure and uses `client: fetchClient(...)` on the client.
+ */
+declare function mixedbreadClient(options: MixedbreadOptions): SearchClient;
+//#endregion
+//#region src/search/client/flexsearch-static.d.ts
+interface FlexsearchStaticOptions {
+  /**
+   * @defaultValue `/api/search`
+   */
+  from?: string;
+  locale?: string;
+  tag?: string | string[];
+}
+declare function flexsearchStaticClient(options?: FlexsearchStaticOptions): SearchClient;
+//#endregion
+//#region src/search/client.d.ts
+interface UseDocsSearch {
+  search: string;
+  setSearch: (v: string) => void;
+  query: {
+    isLoading: boolean;
+    data?: SortedResult[] | 'empty';
+    error?: Error;
+  };
+}
+type ClientPreset = ({
+  /**
+   * @deprecated Pass `client: fetchClient(...)` instead.
+   */
+  type: 'fetch';
+} & FetchOptions) | ({
+  /**
+   * @deprecated Pass `client: staticClient(...)` instead.
+   */
+  type: 'static';
+} & StaticOptions) | ({
+  /**
+   * @deprecated Pass `client: algoliaClient(...)` instead.
+   */
+  type: 'algolia';
+} & AlgoliaOptions) | ({
+  /**
+   * @deprecated Pass `client: oramaCloudClient(...)` instead.
+   */
+  type: 'orama-cloud';
+} & OramaCloudOptions) | ({
+  /**
+   * @deprecated Pass `client: oramaCloudLegacyClient(...)` instead.
+   */
+  type: 'orama-cloud-legacy';
+} & OramaCloudLegacyOptions) | ({
+  /**
+   * @deprecated Pass `client: flexsearchStaticClient(...)` instead.
+   */
+  type: 'flexsearch-static';
+} & FlexsearchStaticOptions) | ({
+  /**
+   * @deprecated Use `createMixedbreadSearchAPI` from `@vezham/docs-core/search/mixedbread` instead.
+   * This client-side approach exposes your API key in the browser.
+   * The server-side approach keeps the key secure and uses `client: fetchClient(...)` on the client.
+   */
+  type: 'mixedbread';
+} & MixedbreadOptions) | {
+  client: SearchClient;
+};
+interface SearchClient {
+  search: (query: string) => Awaitable<SortedResult[]>;
+  deps?: DependencyList;
+}
+/**
+ * Provide a hook to query different official search clients.
+ *
+ * Note: it will re-query when its parameters changed, make sure to define `deps` array if you encounter rendering issues.
+ */
+declare function useDocsSearch(clientOptions: ClientPreset & {
+  /**
+   * The debounced delay for performing a search (in ms).
+   * .
+   * @defaultValue 100
+   */
+  delayMs?: number;
+  /**
+   * still perform search even if query is empty.
+   *
+   * @defaultValue false
+   */
+  allowEmpty?: boolean;
+}, customDeps?: DependencyList): UseDocsSearch;
+//#endregion
+export { staticClient as _, flexsearchStaticClient as a, mixedbreadClient as c, OramaCloudOptions as d, oramaCloudClient as f, oramaStaticClient as g, StaticOptions as h, FlexsearchStaticOptions as i, OramaCloudLegacyOptions as l, algoliaClient as m, SearchClient as n, MixedbreadOptions as o, AlgoliaOptions as p, useDocsSearch as r, SearchMetadata as s, ClientPreset as t, oramaCloudLegacyClient as u, FetchOptions as v, fetchClient as y };

package/dist/codeblock-utils-CyP8qsYv.d.ts

@@ -0,0 +1,29 @@
+import { MdxJsxAttribute, MdxJsxFlowElement } from "mdast-util-mdx";
+import { BlockContent, Text } from "mdast";
+//#region src/mdx-plugins/codeblock-utils.d.ts
+interface CodeBlockTabsOptions {
+  attributes?: MdxJsxAttribute[];
+  defaultValue?: string;
+  persist?: {
+    id: string;
+  } | false;
+  triggers: {
+    value: string;
+    children: (BlockContent | Text)[];
+  }[];
+  tabs: {
+    value: string;
+    children: BlockContent[];
+  }[];
+}
+declare function generateCodeBlockTabs({ persist, defaultValue, triggers, tabs, ...options }: CodeBlockTabsOptions): MdxJsxFlowElement;
+interface CodeBlockAttributes<Name extends string = string> {
+  attributes: Partial<Record<Name, string | number | null>>;
+  rest: string;
+}
+/**
+ * Parse Fumadocs-style code block attributes from meta string, like `title="hello world"`
+ */
+declare function parseCodeBlockAttributes<const Name extends string = string>(meta: string, allowedNames?: Name[]): CodeBlockAttributes<Name>;
+//#endregion
+export { parseCodeBlockAttributes as i, CodeBlockTabsOptions as n, generateCodeBlockTabs as r, CodeBlockAttributes as t };

package/dist/content/github.d.ts

@@ -0,0 +1,41 @@
+//#region src/content/github.d.ts
+interface GetGithubLastCommitOptions {
+  /**
+   * Repository name, like "fumadocs"
+   */
+  repo: string;
+  /** Owner of repository */
+  owner: string;
+  /**
+   * Path to file
+   */
+  path: string;
+  /**
+   * GitHub access token
+   */
+  token?: string;
+  /**
+   * SHA or ref (branch or tag) name.
+   */
+  sha?: string;
+  /**
+   * Base URL for GitHub API
+   * @default "https://api.github.com"
+   * @link https://docs.github.com/en/get-started/using-github-docs/about-versions-of-github-docs#determining-which-github-product-you-use
+   */
+  baseUrl?: string;
+  /**
+   * Custom query parameters
+   */
+  params?: Record<string, string>;
+  options?: RequestInit;
+}
+/**
+ * Get the last edit time of a file using GitHub API
+ *
+ * By default, this will cache the result forever.
+ * Set `options.next.revalidate` to customize this.
+ */
+declare function getGithubLastEdit({ repo, token, owner, path, sha, baseUrl, options, params: customParams }: GetGithubLastCommitOptions): Promise<Date | null>;
+//#endregion
+export { GetGithubLastCommitOptions, getGithubLastEdit };