docusaurus.config.ts

import { themes as prismThemes } from 'prism-react-renderer';
import type { Config } from '@docusaurus/types';
import type * as Preset from '@docusaurus/preset-classic';
import { generateRedirects, createRedirects as createRedirectsBase } from './redirects';

// This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)

const scripts = [];

// `npm run build` sets this to 'production'
// `npm start` and `npm run dev` sets it to 'development'
if (process.env.NODE_ENV === 'production') {
	scripts.push({ src: '/js/reo.js' });
}

// Determine base URL from environment variable or use defaults
// For GitHub Pages deployment: DOCUSAURUS_BASE_URL=/documentation/
// For local development: DOCUSAURUS_BASE_URL=/ (or unset)
// Can also be set via command line: npm run build -- --base-url /documentation/
const baseUrl = process.env.DOCUSAURUS_BASE_URL || '/';

// Determine route base path for docs
// Can be set to '/docs/' if we need docs under a subdirectory
// Default is '/' to serve docs at the root
const routeBasePath = process.env.DOCUSAURUS_ROUTE_BASE_PATH || '/docs'; // matching the production URL structure since this will currently affect some relative links in the docs

// URL can also be overridden if needed
const url = process.env.DOCUSAURUS_URL || 'https://docs.harperdb.io';

// Always log configuration at build time
console.log('Docusaurus URL config:', { url, baseUrl, routeBasePath });

const config: Config = {
	title: 'Harper Docs',
	tagline:
		'Harper fuses database, cache, messaging, and application functions into a single process — delivering performance and simplicity for data-intensive, latency-sensitive applications.',
	favicon: 'img/HarperDogLogo.svg',

	// Future flags, see https://docusaurus.io/docs/api/docusaurus-config#future
	future: {
		v4: true, // Improve compatibility with the upcoming Docusaurus v4
	},

	// Set the production url of your site here
	url,
	// Set the /<baseUrl>/ pathname under which your site is served
	baseUrl,
	// Remove trailing slashes - GitHub Pages handles this fine and makes relative paths intuitive
	trailingSlash: false,

	staticDirectories: ['static'],

	// GitHub pages deployment config.
	// If you aren't using GitHub pages, you don't need these.
	organizationName: 'HarperDB', // Usually your GitHub org/user name.
	projectName: 'documentation', // Usually your repo name.

	onBrokenLinks: 'throw',
	onBrokenMarkdownLinks: 'warn',

	plugins: [
		// Main documentation
		[
			'@docusaurus/plugin-content-docs',
			{
				id: 'default',
				path: './docs',
				sidebarPath: './sidebars.ts',
				routeBasePath,
				editUrl: ({ versionDocsDirPath, docPath }) => {
					// For versioned docs: versionDocsDirPath is like 'versioned_docs/version-4.6'
					// For current docs: versionDocsDirPath is 'docs'
					if (versionDocsDirPath.startsWith('versioned_docs')) {
						// Versioned docs are in versioned_docs/version-X.X/
						return `https://github.com/HarperDB/documentation/blob/main/${versionDocsDirPath}/${docPath}`;
					} else {
						// Current docs are in the root docs/ directory
						return `https://github.com/HarperDB/documentation/blob/main/docs/${docPath}`;
					}
				},
				lastVersion: '4.7',
				includeCurrentVersion: false,
				versions: {
					'4.7': {
						// No banner for 4.7 as it's the latest stable version
						banner: 'none',
					},
					'4.6': {
						// No banner for 4.6 as it's still actively maintained
						banner: 'none',
					},
					'4.5': {
						// No banner for 4.5 as it's still actively maintained
						banner: 'none',
					},
				},
				// Converts npm commands in markdown code blocks to show npm/yarn/pnpm tabs
				remarkPlugins: [[require('@docusaurus/remark-plugin-npm2yarn'), { sync: true }]],
				// Filter out index files that are used as category links
				async sidebarItemsGenerator({ defaultSidebarItemsGenerator, ...args }) {
					const sidebarItems = await defaultSidebarItemsGenerator(args);

					// Function to recursively process sidebar items
					function filterIndexFiles(items: any[]): any[] {
						return items
							.filter((item) => {
								// Filter out index.md files at the root of autogenerated directories
								// when they would be duplicates of category links
								if (item.type === 'doc' && item.id?.endsWith('/index')) {
									// Check if the category metadata has a link to this index
									const dirName = args.item?.dirName;
									if (dirName && item.id === `${dirName}/index`) {
										const categoryMeta = args.categoriesMetadata?.[dirName];
										if (categoryMeta?.link?.type === 'doc' && categoryMeta.link.id === item.id) {
											const versionName = args.version?.versionName || 'current';
											console.log(`✂️ 🔗 [v${versionName}] Removing ${item.id} from ${dirName} (category link exists)`);
											return false;
										}
									}
									// Keep other index files that are in subcategories
									return true;
								}

								// Process categories recursively
								if (item.type === 'category' && item.items) {
									return {
										...item,
										items: filterIndexFiles(item.items),
									};
								}

								return true;
							})
							.map((item) => {
								// For categories, recursively filter their items
								if (item.type === 'category' && item.items) {
									return {
										...item,
										items: filterIndexFiles(item.items),
									};
								}
								return item;
							});
					}

					return filterIndexFiles(sidebarItems);
				},
			},
		],

		// Release Notes documentation
		[
			'@docusaurus/plugin-content-docs',
			{
				id: 'release-notes',
				path: 'release-notes',
				routeBasePath: 'release-notes',
				sidebarPath: './sidebarsReleaseNotes.ts',
				editUrl: 'https://github.com/HarperDB/documentation/blob/main/',
				// Sort by semantic version and filter out index files from sidebar
				async sidebarItemsGenerator({ defaultSidebarItemsGenerator, ...args }) {
					const sidebarItems = await defaultSidebarItemsGenerator(args);

					// Create sortable version string by padding numbers with zeros
					const getSortKey = (id: string): string => {
						// Extract version and pad each part to 3 digits for sorting
						const match = id?.match(/(\d+)\.(\d+)\.(\d+)$/);
						if (match) {
							// Prefix with 'zzz' so version files sort after non-version files
							return `zzz.${match[1].padStart(3, '0')}.${match[2].padStart(3, '0')}.${match[3].padStart(3, '0')}`;
						}
						// Non-version files (like "tucker") will sort first naturally
						return id || '';
					};

					// Sort by padded version string (newest first for versions)
					const sorted = sidebarItems
						.filter((i: any) => !i.id?.endsWith('/index'))
						.sort((a: any, b: any) => {
							const keyA = getSortKey(a.id);
							const keyB = getSortKey(b.id);
							// Reverse comparison so versions are newest first
							return keyB.localeCompare(keyA);
						});

					return sorted;
				},
			},
		],

		// Fabric documentation
		[
			'@docusaurus/plugin-content-docs',
			{
				id: 'fabric',
				path: 'fabric',
				routeBasePath: 'fabric',
				sidebarPath: './sidebarsFabric.ts',
				editUrl: 'https://github.com/HarperDB/documentation/blob/main/',
			},
		],

		// Theme
		[
			'@docusaurus/theme-classic',
			{
				customCss: './src/css/custom.css',
			},
		],

		// Redirects
		[
			'@docusaurus/plugin-client-redirects',
			{
				redirects: generateRedirects(routeBasePath),
				createRedirects: (existingPath: string) => createRedirectsBase(existingPath, routeBasePath),
			},
		],

		// Sitemap
		[
			'@docusaurus/plugin-sitemap',
			{
				createSitemapItems: async (params: any) => {
					const { defaultCreateSitemapItems, ...rest } = params;
					const items = await defaultCreateSitemapItems(rest);
					return items.map((item: any) => {
						// Versioned docs (e.g., /docs/4.5/, /docs/4.4/) - rarely change. could switch to monthly as the dust settles.
						if (/\/docs\/\d+\.\d+\//.test(item.url)) {
							return { ...item, changefreq: 'weekly' };
						}
						// Current/latest docs at /docs/ - most frequently updated
						if (item.url.includes('/docs/')) {
							return { ...item, changefreq: 'daily' };
						}
						// Release notes - fairly frequent updates
						if (item.url.includes('/release-notes/')) {
							return { ...item, changefreq: 'weekly' };
						}
						// Default for everything else
						return { ...item, changefreq: 'weekly' };
					});
				},
			},
		],

		// GA4
		...(process.env.GA4_TRACKING_ID
			? [
					[
						'@docusaurus/plugin-google-gtag',
						{
							trackingID: process.env.GA4_TRACKING_ID || '',
							anonymizeIP: true,
						},
					],
				]
			: []),
	],

	themes: [
		// Use Algolia search in production when env vars are set, otherwise use local search
		...(process.env.NODE_ENV === 'production' && process.env.ALGOLIA_APP_ID && process.env.ALGOLIA_SEARCH_KEY
			? ['@docusaurus/theme-search-algolia']
			: [
					[
						require.resolve('@easyops-cn/docusaurus-search-local'),
						{
							hashed: true,
							language: ['en'],
							indexDocs: true,
							indexBlog: false,
							indexPages: true,
							docsRouteBasePath: routeBasePath,
							highlightSearchTermsOnTargetPage: true,
							searchResultLimits: 8,
							searchBarPosition: 'right',
						},
					],
				]),
		'@docusaurus/theme-mermaid',
	],

	markdown: {
		mermaid: true,
	},

	themeConfig: {
		// Project's social card
		image: 'img/HarperOpenGraph.png',
		// Algolia search configuration (only used when Algolia theme is active)
		algolia: {
			appId: process.env.ALGOLIA_APP_ID || '',
			apiKey: process.env.ALGOLIA_SEARCH_KEY || '',
			indexName: process.env.ALGOLIA_INDEX_NAME || 'harper-docs',
			contextualSearch: true,
			searchPagePath: 'search',
			searchParameters: {},
		},
		navbar: {
			logo: {
				alt: 'Harper Logo',
				src: 'img/HarperPrimaryBlk.svg',
				srcDark: 'img/HarperPrimaryWht.svg',
				href: 'https://www.harper.fast/',
			},
			items: [
				{
					type: 'docSidebar',
					sidebarId: 'docsSidebar',
					position: 'left',
					label: 'Documentation',
				},
				{
					// Link directly to v4 (current version) instead of overview page
					type: 'doc',
					docsPluginId: 'release-notes',
					docId: 'v4-tucker/index',
					position: 'left',
					label: 'Release Notes',
				},
				{
					type: 'docSidebar',
					sidebarId: 'fabricSidebar',
					docsPluginId: 'fabric',
					position: 'left',
					label: 'Fabric',
				},
				{
					type: 'docsVersionDropdown',
					position: 'right',
					dropdownActiveClassDisabled: true,
				},
				{
					href: 'https://github.com/HarperDB/documentation',
					label: 'GitHub',
					position: 'right',
				},
			],
		},
		footer: {
			style: 'dark',
			links: [
				{
					title: 'Documentation',
					items: [
						{
							label: 'Quickstart',
							to: `${routeBasePath}/getting-started/quickstart`,
						},
						// {
						// 	label: 'Developers',
						// 	to: `${routeBasePath}/developers`,
						// },
						{
							label: 'Administration',
							to: `${routeBasePath}/administration`,
						},
					],
				},
				{
					title: 'Community',
					items: [
						{
							label: 'Discord',
							href: 'https://discord.gg/VzZuaw3Xay',
						},
						{
							label: 'LinkedIn',
							href: 'https://www.linkedin.com/company/harperfast/',
						},
						{
							label: 'X (Twitter)',
							href: 'https://twitter.com/harper_fast',
						},
					],
				},
				{
					title: 'More',
					items: [
						{
							label: 'Harper Fast',
							href: 'https://www.harper.fast',
						},
						{
							label: 'Blog',
							href: 'https://www.harper.fast/resources',
						},
						{
							label: 'GitHub',
							href: 'https://github.com/HarperFast',
						},
						{
							label: 'Contact',
							href: 'mailto:opensource@harperdb.io',
						},
					],
				},
			],
			copyright: `Copyright © ${new Date().getFullYear()} HarperDB, Inc.`,
		},
		prism: {
			theme: prismThemes.github,
			darkTheme: prismThemes.dracula,
		},
	} satisfies Preset.ThemeConfig,
	scripts,
};

export default config;