feat: setup docusaurus EUI theme (#7827)

packages/docusaurus-theme/.gitignore

@@ -0,0 +1,8 @@
+# Dependencies
+/node_modules
+
+# Production
+/lib
+
+yarn-debug.log*
+yarn-error.log*

packages/docusaurus-theme/README.md

@@ -0,0 +1,42 @@
+# EUI Docusaurus theme
+
+`@elastic/eui-docusaurus-theme`
+
+EUI theme for [Docusaurus](https://docusaurus.io/) made for the new EUI [documentation website](https://eui.elastic.co).
+
+## Installation and usage
+
+This package is not yet published to npm.
+
+## Local development
+
+### Prerequisites
+
+This package requires Node.js (check current version in [.nvmrc](/.nvmrc)) to be installed
+and [corepack](https://nodejs.org/api/corepack.html) to be enabled.
+
+### Installing dependencies
+
+Please run `yarn` to install dependencies:
+
+```shell
+yarn
+```
+
+### Building the package
+
+```shell
+yarn build
+```
+
+### Building in watch mode
+
+Run the following command to build this package whenever a file is edited:
+
+```shell
+yarn start
+```
+
+Please note that this package is configured to do incremental builds and sometimes `tsc` may not update
+the `lib` directory with your latest changes if you rename or delete files.
+If that's the case please run `yarn build`.

packages/docusaurus-theme/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@elastic/eui-docusaurus-theme",
+  "version": "0.1.0",
+  "description": "EUI theme for Docusaurus",
+  "private": true,
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "build": "tsc --build",
+    "start": "tsc --watch"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tkajtoch/eui.git",
+    "directory": "packages/docusaurus-theme"
+  },
+  "devDependencies": {
+    "@docusaurus/types": "^3.4.0",
+    "@types/react": "^18",
+    "@types/react-dom": "^18",
+    "typescript": "~5.4.5"
+  },
+  "main": "lib/index.js",
+  "exports": {
+    "./lib/*": "./lib/*",
+    "./src/*": "./src/*",
+    ".": {
+      "default": "./lib/index.js"
+    }
+  },
+  "dependencies": {
+    "@docusaurus/core": "^3.4.0",
+    "@docusaurus/module-type-aliases": "^3.4.0",
+    "@docusaurus/utils-validation": "^3.4.0",
+    "@elastic/datemath": "^5.0.3",
+    "@elastic/eui": "94.5.0",
+    "@emotion/css": "^11.11.2",
+    "@emotion/react": "^11.11.4",
+    "moment": "^2.30.1"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  }
+}

packages/docusaurus-theme/src/index.ts

@@ -0,0 +1,13 @@
+import type { Plugin } from '@docusaurus/types';
+
+export default function euiDocusaurusTheme(): Plugin<void> {
+  return {
+    name: 'eui-docusaurus-theme',
+    getThemePath() {
+      return '../lib/theme';
+    },
+    getTypeScriptThemePath() {
+      return '../src/theme';
+    },
+  };
+}

packages/docusaurus-theme/src/theme/Footer/index.tsx

@@ -0,0 +1,47 @@
+import { css } from '@emotion/react';
+import { EuiText, EuiLink, UseEuiTheme, EuiThemeProvider, useEuiMemoizedStyles } from '@elastic/eui';
+
+const ELASTIC_LICENSE_URL = "https://github.com/elastic/eui/blob/main/licenses/ELASTIC-LICENSE-2.0.md";
+const SSPL_LICENSE_URL = "https://github.com/elastic/eui/blob/main/licenses/SSPL-LICENSE.md";
+
+const getFooterStyles = ({ euiTheme }: UseEuiTheme) => {
+  return {
+    root: css`
+      background: #1C1E23; // Color not available in EUI
+      border-radius: ${euiTheme.size.s} ${euiTheme.size.s} 0 0;
+      padding: ${euiTheme.size.l};
+      text-align: center;
+    `,
+    heart: css`
+      color: ${euiTheme.colors.accent};
+    `,
+  };
+};
+
+const Footer = () => {
+  const styles = useEuiMemoizedStyles(getFooterStyles);
+
+  return (
+    <EuiThemeProvider colorMode="inverse">
+      <footer css={styles.root}>
+        <EuiText textAlign="center" size="s">
+          EUI is dual-licensed under {' '}
+          <EuiLink href={ELASTIC_LICENSE_URL}>
+            Elastic License 2.0
+          </EuiLink>
+          {' and '}
+          <EuiLink href={SSPL_LICENSE_URL}>
+            Server Side Public License, v 1
+          </EuiLink>
+          {' | '}
+          Crafted with <span role="img" aria-label="love" css={styles.heart}>❤</span> by{' '}
+          <EuiLink href="https://elastic.co">
+            Elastic
+          </EuiLink>
+        </EuiText>
+      </footer>
+    </EuiThemeProvider>
+  );
+};
+
+export default Footer;

packages/website/src/theme/MDXComponents/index.js → packages/docusaurus-theme/src/theme/MDXComponents/index.ts

@@ -6,8 +6,8 @@
  * Side Public License, v 1.
  */
 
-import OriginalMDXComponents from '@theme-original/MDXComponents';
-import { Badge } from '@site/src/components/badge';
+import OriginalMDXComponents from '@theme-init/MDXComponents';
+import { Badge } from '../../components/badge';
 
 const MDXComponents = {
   ...OriginalMDXComponents,

packages/website/src/theme/Root.tsx → packages/docusaurus-theme/src/theme/Root.tsx

@@ -8,6 +8,7 @@
 
 import { EuiProvider } from '@elastic/eui';
 import { Props } from '@theme/Root';
+import '@elastic/eui/dist/eui_theme_light.css';
 
 // Wrap docusaurus root component with <EuiProvider>
 // See https://docusaurus.io/docs/swizzling#wrapper-your-site-with-root

packages/docusaurus-theme/tsconfig.base.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    /* Emit */
+    "target": "ES2020",
+    "lib": ["ESNext", "DOM"],
+    "declaration": true,
+    // These two options will be selectively overridden in each project.
+    // Utility libraries will have source maps on, but plugins will not.
+    "declarationMap": false,
+    "sourceMap": false,
+    "jsx": "react-jsx",
+    "jsxImportSource": "@emotion/react",
+    "importHelpers": true,
+    "noEmitHelpers": true,
+    // Avoid accidentally using this config to build
+    "noEmit": true,
+
+    /* Strict Type-Checking Options */
+    "allowUnreachableCode": false,
+    // Too hard to turn on
+    "exactOptionalPropertyTypes": false,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitOverride": true,
+    "noImplicitReturns": true,
+    // `process.env` is usually accessed as property
+    "noPropertyAccessFromIndexSignature": false,
+    "noUncheckedIndexedAccess": true,
+    /* strict family */
+    "strict": true,
+    "alwaysStrict": true,
+    "noImplicitAny": true,
+    "noImplicitThis": true,
+    "strictBindCallApply": true,
+    "strictFunctionTypes": true,
+    "strictNullChecks": true,
+    "strictPropertyInitialization": true,
+    "useUnknownInCatchVariables": true,
+    /* Handled by ESLint */
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "importsNotUsedAsValues": "remove",
+
+    /* Module Resolution */
+    "moduleResolution": "Node",
+    "resolveJsonModule": true,
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "isolatedModules": true,
+    "allowJs": true,
+    "skipLibCheck": true, // @types/webpack and webpack/types.d.ts are not the same thing
+    "types": [
+      "@docusaurus/module-type-aliases"
+    ]
+  },
+  "include": ["./**/*", "./**/.eslintrc.js"],
+  "exclude": [
+    "node_modules",
+    "coverage/**",
+    "**/lib/**/*",
+    "website/**",
+    "**/__mocks__/**/*",
+    "**/__fixtures__/**/*",
+    "examples/**",
+    "packages/create-docusaurus/templates/**"
+  ]
+}

packages/docusaurus-theme/tsconfig.client.json

@@ -0,0 +1,17 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "incremental": true,
+    "moduleResolution": "bundler",
+    "module": "esnext",
+    "target": "esnext",
+    "esModuleInterop": true,
+    "composite": true,
+    "rootDir": "src",
+    "outDir": "lib",
+    "tsBuildInfoFile": "lib/.tsbuildinfo-client"
+  },
+  "include": ["src/client", "src/components", "src/theme", "src/*.d.ts"],
+  "exclude": ["**/__tests__/**"]
+}

packages/docusaurus-theme/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "references": [{"path": "./tsconfig.client.json"}],
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ESNext"],
+    "declaration": true,
+    "sourceMap": true,
+    "jsx": "react-jsx",
+    "jsxImportSource": "@emotion/react",
+    "noEmitHelpers": true,
+    "incremental": true,
+    "tsBuildInfoFile": "lib/.tsbuildinfo",
+    "rootDir": "src",
+    "outDir": "lib",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "moduleResolution": "Node",
+    "types": [
+      "@docusaurus/module-type-aliases"
+    ]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["src/client", "src/theme", "**/__tests__/**"]
+}

packages/website/README.md

@@ -1,41 +1,57 @@
-# Website
+# EUI documentation website
 
-This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+This package contains sources of the upcoming new EUI documentation website
+built with [Docusaurus](https://docusaurus.io/), an open-source documentation
+platform powered by React.
 
-### Installation
+This is a **private** package and is not meant to be published to npm.
+If you're looking for EUI components or utilities, check out our other [packages](../).
 
-```
-$ yarn
-```
+## Local development
 
-### Local Development
+### Prerequisites
 
-```
-$ yarn start
+Like other packages in this repository, this package requires Node.js (check version in [.nvmrc](/.nvmrc)) 
+to be installed and [corepack](https://nodejs.org/api/corepack.html) enabled.
+
+### Installing dependencies
+
+Please run `yarn` to install dependencies:
+
+```shell
+yarn
 ```
 
-This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+### Building helper packages
 
-### Build
+Before you run scripts, it's mandatory to build all local dependency packages:
 
+```shell
+yarn workspaces foreach -Rpt --from @elastic/eui-website run build
 ```
-$ yarn build
+
+### Running the development server
+
+Run a local development server with hot reloading capabilities:
+
+```shell
+yarn start
 ```
 
-This command generates static content into the `build` directory and can be served using any static contents hosting service.
+Please note that this command does not watch for changes in other packages' sources
+(e.g., the [theme](../docusaurus-theme) package). Please check out each package's
+README to see if watch mode is available and how to use it.
 
-### Deployment
+### Building the website
 
-Using SSH:
+This step is usually unnecessary to run locally unless you're testing production builds.
 
-```
-$ USE_SSH=true yarn deploy
+```shell
+yarn build
 ```
 
-Not using SSH:
+### Running type checks
 
+```shell
+yarn typecheck
 ```
-$ GIT_USER=<Your GitHub username> yarn deploy
-```
-
-If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

packages/website/docusaurus.config.ts

@@ -35,6 +35,10 @@ const config: Config = {
     locales: ['en'],
   },
 
+  themes: [
+    '@elastic/eui-docusaurus-theme',
+  ],
+
   presets: [
     [
       'classic',
@@ -49,9 +53,6 @@ const config: Config = {
           editUrl:
             'https://github.com/elastic/eui/tree/main/website/',
         },
-        theme: {
-          customCss: './src/css/custom.css',
-        },
       } satisfies Preset.Options,
     ],
   ],