@netfoundry/docusaurus-theme 0.1.0

package/css/theme.css

@@ -0,0 +1,15 @@
+/**
+ * NetFoundry Docusaurus Theme - Combined Styles
+ *
+ * This file is automatically loaded by the theme via getClientModules().
+ * It imports all necessary CSS from @netfoundry/docusaurus-shared.
+ *
+ * Consuming projects no longer need to manually add these imports
+ * to their custom.css files.
+ */
+
+/* Core theme CSS with variables and layout */
+@import "@netfoundry/docusaurus-shared/index.css";
+
+/* Legacy design system variables and comprehensive styling */
+@import "@netfoundry/docusaurus-shared/css/legacy.css";

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@netfoundry/docusaurus-theme",
+  "version": "0.1.0",
+  "description": "NetFoundry Docusaurus theme with shared layout, footer, and styling",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "theme",
+    "css"
+  ],
+  "scripts": {
+    "build": "echo 'No build needed - theme uses source files directly'"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@docusaurus/core": "^3",
+    "@docusaurus/theme-classic": "^3",
+    "@docusaurus/theme-common": "^3",
+    "react": "^18 || ^19",
+    "react-dom": "^18 || ^19"
+  },
+  "dependencies": {
+    "@netfoundry/docusaurus-shared": "^0.1.1",
+    "clsx": "^2.0.0"
+  },
+  "devDependencies": {
+    "@docusaurus/types": "^3",
+    "typescript": "^5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/netfoundry/docusaurus-shared.git",
+    "directory": "lib/packages/docusaurus-theme"
+  },
+  "keywords": [
+    "docusaurus",
+    "docusaurus-theme",
+    "netfoundry",
+    "openziti"
+  ],
+  "license": "Apache-2.0"
+}

package/src/index.ts

@@ -0,0 +1,46 @@
+import type { LoadContext, Plugin } from '@docusaurus/types';
+import type { NetFoundryThemeOptions } from './options';
+import path from 'path';
+
+export default function themeNetFoundry(
+  context: LoadContext,
+  options: NetFoundryThemeOptions = {}
+): Plugin {
+  return {
+    name: '@netfoundry/docusaurus-theme',
+
+    // Register theme component overrides
+    getThemePath() {
+      return path.resolve(__dirname, '../theme');
+    },
+
+    // For TypeScript development
+    getTypeScriptThemePath() {
+      return path.resolve(__dirname, '../theme');
+    },
+
+    // Automatically inject CSS
+    getClientModules() {
+      const modules: string[] = [
+        require.resolve('../css/theme.css'),
+      ];
+
+      // Add custom CSS if specified in options
+      if (options.customCss) {
+        const customCssArray = Array.isArray(options.customCss)
+          ? options.customCss
+          : [options.customCss];
+        modules.push(...customCssArray);
+      }
+
+      return modules;
+    },
+  };
+}
+
+// Re-export types for consumers (types are safe to export at config time)
+export type { NetFoundryThemeOptions, NetFoundryThemeConfig } from './options';
+
+// NOTE: UI components (defaultNetFoundryFooterProps, defaultSocialProps, etc.)
+// should be imported directly from '@netfoundry/docusaurus-shared/ui' in client code,
+// not from this theme entry point, as this file runs at Node.js config time.

package/src/options.ts

@@ -0,0 +1,95 @@
+import type { ReactNode } from 'react';
+
+/**
+ * Social media link configuration for the footer
+ */
+export interface SocialProps {
+  githubUrl?: string;
+  twitterUrl?: string;
+  linkedInUrl?: string;
+  youtubeUrl?: string;
+  facebookUrl?: string;
+  instagramUrl?: string;
+}
+
+/**
+ * Footer configuration for the theme
+ */
+export interface FooterConfig {
+  /** Description text shown in the footer */
+  description?: string;
+  /** Social media links */
+  socialProps?: SocialProps;
+  /** Documentation section links (as ReactNode for JSX support) */
+  documentationLinks?: ReactNode[];
+  /** Community section links */
+  communityLinks?: ReactNode[];
+  /** Resources section links */
+  resourceLinks?: ReactNode[];
+}
+
+/**
+ * Star banner configuration
+ */
+export interface StarBannerConfig {
+  /** GitHub repository URL */
+  repoUrl: string;
+  /** Label text for the star button */
+  label: string;
+}
+
+/**
+ * Options passed to the theme plugin in docusaurus.config.ts
+ *
+ * @example
+ * ```ts
+ * themes: [
+ *   ['@netfoundry/docusaurus-theme', {
+ *     customCss: require.resolve('./src/css/custom.css'),
+ *   }],
+ * ],
+ * ```
+ */
+export interface NetFoundryThemeOptions {
+  /** Custom CSS file path(s) to include */
+  customCss?: string | string[];
+}
+
+/**
+ * Theme configuration in themeConfig.netfoundry
+ *
+ * @example
+ * ```ts
+ * themeConfig: {
+ *   netfoundry: {
+ *     footer: {
+ *       description: 'My site description',
+ *       socialProps: {
+ *         githubUrl: 'https://github.com/my-org/repo',
+ *       },
+ *     },
+ *     starBanner: {
+ *       repoUrl: 'https://github.com/my-org/repo',
+ *       label: 'Star us on GitHub',
+ *     },
+ *     showStarBanner: true,
+ *   },
+ * },
+ * ```
+ */
+export interface NetFoundryThemeConfig {
+  /** Footer configuration */
+  footer?: FooterConfig;
+  /** Star banner configuration */
+  starBanner?: StarBannerConfig;
+  /** Whether to show the star banner (default: false) */
+  showStarBanner?: boolean;
+}
+
+/**
+ * Extended Docusaurus ThemeConfig with NetFoundry configuration
+ */
+export interface ThemeConfigWithNetFoundry {
+  netfoundry?: NetFoundryThemeConfig;
+  [key: string]: unknown;
+}

package/theme/Layout/index.tsx

@@ -0,0 +1,74 @@
+import React, { type ReactNode } from 'react';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import {
+  NetFoundryLayout,
+  defaultNetFoundryFooterProps,
+  defaultSocialProps,
+} from '@netfoundry/docusaurus-shared/ui';
+import type { ThemeConfigWithNetFoundry } from '../../src/options';
+
+export interface LayoutProps {
+  children: ReactNode;
+  noFooter?: boolean;
+  wrapperClassName?: string;
+  title?: string;
+  description?: string;
+}
+
+/**
+ * NetFoundry theme Layout component.
+ *
+ * This component wraps NetFoundryLayout and reads configuration from
+ * themeConfig.netfoundry in docusaurus.config.ts.
+ *
+ * To customize further, swizzle this component:
+ * npx docusaurus swizzle @netfoundry/docusaurus-theme Layout --wrap
+ */
+export default function Layout({
+  children,
+  noFooter,
+  wrapperClassName,
+  title,
+  description,
+}: LayoutProps): ReactNode {
+  const { siteConfig } = useDocusaurusContext();
+  const themeConfig = siteConfig.themeConfig as ThemeConfigWithNetFoundry;
+  const nfConfig = themeConfig.netfoundry ?? {};
+
+  // Build footer props from config, falling back to defaults
+  const footerProps = noFooter
+    ? undefined
+    : {
+        ...defaultNetFoundryFooterProps(),
+        ...nfConfig.footer,
+        socialProps: {
+          ...defaultSocialProps,
+          ...nfConfig.footer?.socialProps,
+        },
+      };
+
+  // Build star props if enabled
+  const starProps =
+    nfConfig.showStarBanner && nfConfig.starBanner
+      ? {
+          repoUrl: nfConfig.starBanner.repoUrl,
+          label: nfConfig.starBanner.label,
+        }
+      : undefined;
+
+  return (
+    <NetFoundryLayout
+      title={title}
+      description={description}
+      className={wrapperClassName}
+      noFooter={noFooter}
+      footerProps={footerProps}
+      starProps={starProps}
+      meta={{
+        siteName: siteConfig.title,
+      }}
+    >
+      {children}
+    </NetFoundryLayout>
+  );
+}