docs: rewrite documentation site with Docusaurus

.gitignore

@@ -139,6 +139,11 @@ dist
 # Docusaurus cache and generated files
 
 .docusaurus
+website/build/
+website/.docusaurus/
+
+# Docusaurus OpenAPI plugin generated docs
+docs/api/
 
 # Serverless directories
 

.prettierignore

@@ -5,4 +5,6 @@ src/generated
 src/types/i18nresources.d.ts
 docs/reference/endpoint-inventory.json
 docs/reference/endpoint-reference.md
-.claude/settings.local.json
+docs/api/
+.claude/settings.local.json
+website/build/

eslint.config.mjs

@@ -76,6 +76,7 @@ export default [
       '**/.prettierrc.js',
       '.storybook/**/*',
       'storybook-static/**/*',
+      'website/**/*',
     ],
   },
   {

website/.gitignore

@@ -0,0 +1,6 @@
+node_modules/
+.docusaurus/
+build/
+.cache-loader/
+package-lock.json
+openapi/

website/docusaurus.config.ts

@@ -0,0 +1,141 @@
+import type { Config } from '@docusaurus/types'
+import type * as Preset from '@docusaurus/preset-classic'
+import { themes as prismThemes } from 'prism-react-renderer'
+
+const config: Config = {
+  title: 'Gusto Embedded',
+  tagline: 'Embedded Payroll React SDK Documentation',
+  favicon: 'img/favicon.svg',
+
+  url: 'http://localhost',
+  baseUrl: '/',
+
+  onBrokenLinks: 'throw',
+  onBrokenAnchors: 'throw',
+
+  markdown: {
+    format: 'detect',
+  },
+
+  i18n: {
+    defaultLocale: 'en',
+    locales: ['en'],
+  },
+
+  themes: [
+    [
+      require.resolve('@easyops-cn/docusaurus-search-local'),
+      {
+        hashed: true,
+        indexBlog: false,
+        docsRouteBasePath: '/docs',
+        docsDir: '../docs',
+      },
+    ],
+  ],
+
+  presets: [
+    [
+      'classic',
+      {
+        docs: {
+          path: '../docs',
+          routeBasePath: 'docs',
+          sidebarPath: './sidebars.ts',
+          breadcrumbs: true,
+        },
+        blog: false,
+        theme: {
+          customCss: ['./src/css/custom.css'],
+        },
+      } satisfies Preset.Options,
+    ],
+  ],
+
+  plugins: [
+    function webpackPolyfills() {
+      return {
+        name: 'webpack-node-polyfills',
+        configureWebpack() {
+          return {
+            resolve: {
+              fallback: {
+                path: require.resolve('path-browserify'),
+              },
+            },
+          }
+        },
+      }
+    },
+  ],
+
+  themeConfig: {
+    colorMode: {
+      defaultMode: 'light',
+      respectPrefersColorScheme: false,
+    },
+    navbar: {
+      title: 'SDK',
+      logo: {
+        alt: 'Gusto Embedded SDK',
+        src: 'img/gusto-logo.svg',
+      },
+      items: [
+        {
+          type: 'docSidebar',
+          sidebarId: 'docs',
+          position: 'left',
+          label: 'Docs',
+        },
+        {
+          href: 'https://github.com/Gusto/embedded-react-sdk',
+          label: 'GitHub',
+          position: 'right',
+        },
+      ],
+    },
+    footer: {
+      style: 'dark',
+      links: [
+        {
+          title: 'Get Started',
+          items: [
+            { label: 'What is the SDK?', to: '/docs/what-is-the-gep-react-sdk' },
+            { label: 'Getting Started', to: '/docs/getting-started' },
+            { label: 'Workflows Overview', to: '/docs/workflows-overview' },
+          ],
+        },
+        {
+          title: 'Guides',
+          items: [
+            { label: 'Theming', to: '/docs/theming' },
+            { label: 'Component Adapter', to: '/docs/component-adapter' },
+            { label: 'Integration Guide', to: '/docs/integration-guide' },
+            { label: 'Hooks (Experimental)', to: '/docs/hooks' },
+          ],
+        },
+        {
+          title: 'Resources',
+          items: [
+            {
+              label: 'GitHub',
+              href: 'https://github.com/Gusto/embedded-react-sdk',
+            },
+            {
+              label: 'Gusto Developer Portal',
+              href: 'https://docs.gusto.com/embedded-payroll/docs/introduction',
+            },
+          ],
+        },
+      ],
+      copyright: `Copyright © ${new Date().getFullYear()} Gusto, Inc.`,
+    },
+    prism: {
+      theme: prismThemes.github,
+      darkTheme: prismThemes.dracula,
+      additionalLanguages: ['bash', 'json', 'ruby', 'python', 'java'],
+    },
+  } satisfies Preset.ThemeConfig,
+}
+
+export default config

website/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "embedded-react-sdk-docs",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "docusaurus": "docusaurus",
+    "start": "docusaurus start",
+    "build": "docusaurus build",
+    "swizzle": "docusaurus swizzle",
+    "deploy": "docusaurus deploy",
+    "clear": "docusaurus clear",
+    "serve": "docusaurus serve"
+  },
+  "dependencies": {
+    "@docusaurus/core": "^3.7.0",
+    "@docusaurus/preset-classic": "^3.7.0",
+    "@easyops-cn/docusaurus-search-local": "^0.55.1",
+    "@mdx-js/react": "^3.0.0",
+    "clsx": "^2.0.0",
+    "path-browserify": "^1.0.1",
+    "prism-react-renderer": "^2.3.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  },
+  "devDependencies": {
+    "@docusaurus/module-type-aliases": "^3.7.0",
+    "@docusaurus/tsconfig": "^3.7.0",
+    "@docusaurus/types": "^3.7.0",
+    "typescript": "~5.8.0"
+  },
+  "browserslist": {
+    "production": [
+      ">0.5%",
+      "not dead",
+      "not op_mini all"
+    ],
+    "development": [
+      "last 3 chrome version",
+      "last 3 firefox version",
+      "last 5 safari version"
+    ]
+  },
+  "engines": {
+    "node": ">=18.0"
+  }
+}

website/sidebars.ts

@@ -0,0 +1,103 @@
+import type { SidebarsConfig } from '@docusaurus/plugin-content-docs'
+
+const sidebars: SidebarsConfig = {
+  docs: [
+    'what-is-the-gep-react-sdk',
+    {
+      type: 'category',
+      label: 'Deciding to build with the SDK',
+      link: { type: 'doc', id: 'deciding-to-build-with-the-sdk/deciding-to-build-with-the-sdk' },
+      items: [
+        'deciding-to-build-with-the-sdk/build-pathways-sdk-flows-api',
+        'deciding-to-build-with-the-sdk/component-types',
+      ],
+    },
+    {
+      type: 'category',
+      label: 'Getting Started',
+      link: { type: 'doc', id: 'getting-started/getting-started' },
+      items: ['getting-started/authentication', 'getting-started/proxy-security-partner-guidance'],
+    },
+    {
+      type: 'category',
+      label: 'Workflows Overview',
+      link: { type: 'doc', id: 'workflows-overview/workflows-overview' },
+      items: [
+        'workflows-overview/company-onboarding',
+        {
+          type: 'category',
+          label: 'Employee Onboarding',
+          link: { type: 'doc', id: 'workflows-overview/employee-onboarding/employee-onboarding' },
+          items: ['workflows-overview/employee-onboarding/employee-self-onboarding'],
+        },
+        'workflows-overview/employee-dashboard',
+        'workflows-overview/employee-termination',
+        'workflows-overview/run-payroll',
+        'workflows-overview/off-cycle-payroll',
+        'workflows-overview/dismissal-payroll',
+        'workflows-overview/transition-payroll',
+        'workflows-overview/contractor-onboarding',
+        'workflows-overview/contractor-payments',
+        'workflows-overview/information-requests',
+      ],
+    },
+    {
+      type: 'category',
+      label: 'Component Adapter',
+      link: { type: 'doc', id: 'component-adapter/component-adapter' },
+      items: [
+        'component-adapter/how-the-component-adapter-works',
+        'component-adapter/setting-up-your-component-adapter',
+        'component-adapter/component-adapter-types',
+        'component-adapter/component-inventory',
+        'component-adapter/component-adapter-faq',
+      ],
+    },
+    {
+      type: 'category',
+      label: 'Theming',
+      link: { type: 'doc', id: 'theming/theming' },
+      items: ['theming/theme-variables', 'theming/theming-guide'],
+    },
+    {
+      type: 'category',
+      label: 'Integration Guide',
+      link: { type: 'doc', id: 'integration-guide/integration-guide' },
+      items: [
+        'integration-guide/versioning',
+        'integration-guide/event-handling',
+        'integration-guide/event-types',
+        'integration-guide/request-interceptors',
+        'integration-guide/customizing-sdk-ui',
+        'integration-guide/composition',
+        'integration-guide/providing-your-own-data',
+        'integration-guide/translation',
+        'integration-guide/routing',
+        'integration-guide/error-handling',
+        'integration-guide/observability',
+        'integration-guide/observability-examples',
+      ],
+    },
+    {
+      type: 'category',
+      label: 'Hooks (Experimental)',
+      link: { type: 'doc', id: 'hooks/hooks' },
+      items: [
+        'hooks/useEmployeeDetailsForm',
+        'hooks/useCompensationForm',
+        'hooks/useWorkAddressForm',
+      ],
+    },
+    {
+      type: 'category',
+      label: 'Reference',
+      items: [
+        'reference/endpoint-reference',
+        'reference/jobs-and-compensations',
+        'reference/proxy-examples',
+      ],
+    },
+  ],
+}
+
+export default sidebars