@elastic/eui-docusaurus-preset 1.0.0

package/LICENSE.txt

@@ -0,0 +1,6 @@
+Source code in this repository is covered by (i) a dual license under the Server
+Side Public License, v 1 and the Elastic License 2.0 or (ii) an Apache License
+2.0 compatible license or (iii) solely under the Elastic License 2.0, in each
+case, as noted in the applicable header. The default throughout the repository
+is a dual license under the Server Side Public License, v 1 and the Elastic
+License 2.0, unless the header specifies another license.

package/README.md

@@ -0,0 +1,216 @@
+# `@elastic/eui-docusaurus-preset`
+
+EUI custom [Docusaurus](https://docusaurus.io/) preset made for the EUI [documentation website](https://eui.elastic.co).
+
+## Overview
+
+The preset comes with themes and plugins configured.
+
+### Themes
+
+| Theme                           | Description                                        |
+|---------------------------------|----------------------------------------------------|
+| `@docusaurus/theme-classic`     | Base Docusaurus theme (required for compatibility) |
+| `@elastic/eui-docusaurus-theme` | EUI custom theme for Docusaurus                    |
+
+### Plugins
+
+| Plugin                                 | Description.                                                        | Enabled by default?       |
+|----------------------------------------|---------------------------------------------------------------------|---------------------------|
+| `ignore-styles-plugin`                 | Prevents Infima and some inherited styles from polluting global CSS | Yes                       |
+| `@docusaurus/plugin-content-docs`      | Documentation pages support                                         | Yes (configurable)        |
+| `@docusaurus/plugin-content-pages`     | Static pages support                                                | Yes (configurable)        |
+| `@docusaurus/plugin-svgr`              | SVG import support                                                  | Yes (configurable)        |
+| `@docusaurus/plugin-content-blog`      | Blog support                                                        | Yes (configurable)        |
+| `@docusaurus/plugin-sitemap`           | Sitemap generation (for SEO)                                        | Only in production builds |
+| `@docusaurus/plugin-google-analytics`  | Google Analytics integration                                        | If configured             |
+| `@docusaurus/plugin-google-tag-manager`| Google Tag Manager integration                                      | If configured             |
+| `@docusaurus/plugin-google-gtag`       | Google Global Site Tag integration                                  | If configured             |
+
+## Usage
+
+The EUI preset uses the [preset constructor](https://docusaurus.io/docs/using-plugins#creating-presets) to define the theme (`@elastic/eui-docusaurus-theme`) and plugins.
+
+To use it in your Docusaurus project, install the package:
+
+```shell
+# npm
+npm install @elastic/eui-docusaurus-preset
+
+# pnpm
+pnpm add @elastic/eui-docusaurus-preset
+
+# Yarn
+yarn add @elastic/eui-docusaurus-preset
+```
+
+and in your `docusaurus.config.ts` file, add:
+
+```ts
+const config: Config = {
+    // ...
+    presets: [
+        [
+            require.resolve("@elastic/eui-docusaurus-preset"),
+            {
+                docs: {
+                    sidebarPath: "./sidebars.ts",
+                },
+            } satisfies Preset.Options,
+        ],
+    ],
+    // ...
+}
+```
+
+### Theme only
+
+Docusaurus uses Infima, its default CSS framework, to style the classic theme (`@docusaurus/theme-classic`). The EUI Docusaurus theme is based on the classic theme, but Infima's global styles often override or conflict with EUI's design system, leading to inconsistent appearance. The `ignore-styles-plugin` disables Infima's styles, ensuring the EUI theme displays correctly. For this reason, we highly recommend using the preset rather than the standalone theme.
+
+If you prefer to use only the theme, refer to [Theme only](../docusaurus-theme/README.md#theme-only) section in `@elastic/eui-docusaurus-theme`.
+
+## Local development
+
+### Prerequisites
+
+This package requires:
+
+- Node.js (check current version in [.nvmrc](../../.nvmrc)),
+- [corepack](https://nodejs.org/api/corepack.html).
+
+### 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
+```
+
+:::warning
+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`.
+:::
+
+### Test with EUI documentation website
+
+Run the following command from the root of the mono-repository to run the website:
+
+```shell
+yarn workspace @elastic/eui-website start
+```
+
+You can pair it with the watch mode when modifying the Docusaurus theme.
+
+### Test locally with your own Docusaurus project
+
+You should have a Docusaurus project running. If you want to test EUI theme with a fresh project, you should create a [Docusaurus scaffolded project website](https://docusaurus.io/docs/installation).
+
+Run the following command to create a Docusaurus project:
+
+```shell
+npx create-docusaurus@latest my-website classic --typescript
+```
+
+Install `yalc` globally if you haven't already:
+
+```shell
+npm install -g yalc
+```
+
+In the root of the mono-repository, run the following commands to build and publish the preset locally:
+
+```shell
+yarn workspace @elastic/eui-docusaurus-preset build
+
+# Publish the preset locally
+cd packages/docusaurus-preset
+yalc publish
+```
+
+In your project, install EUI dependencies:
+
+```shell
+# npm
+npm install @elastic/eui @elastic/charts @emotion/react @emotion/css moment
+
+# pnpm
+pnpm add @elastic/eui @elastic/charts @emotion/react @emotion/css moment
+
+# Yarn
+yarn add @elastic/eui @elastic/charts @emotion/react @emotion/css moment
+```
+
+and add the locally published packages:
+
+```shell
+yalc add @elastic/eui-docusaurus-preset
+
+# npm
+npm install
+
+# pnpm
+pnpm install
+
+# Yarn
+yarn
+```
+
+Configure Docusaurus to use the locally built preset as outlined in the [Usage section](#usage).
+
+#### Making changes
+
+When you make changes to the preset, rebuild and republish the packages:
+
+```shell
+# From the mono-repository root
+yarn workspace @elastic/eui-docusaurus-preset build
+
+cd packages/docusaurus-preset  
+yalc publish --push
+```
+
+The `--push` flag automatically updates all projects using these packages.
+
+Restart your Docusaurus development server:
+
+```shell
+# npm
+npm run start
+
+# pnpm
+pnpm start
+
+# Yarn
+yarn start
+```
+
+When you're done testing, remove the locally published packages from your project:
+
+```shell
+# In your project
+yalc remove @elastic/eui-docusaurus-preset
+
+# npm
+npm install
+
+# pnpm
+pnpm install
+
+# Yarn
+yarn
+```

package/lib/index.js

@@ -0,0 +1,67 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+/**
+ * Docusaurus plugin to ignore any unwanted style imports, e.g. like Infima stylesheet imports.
+ * This is needed so that Infima doesn't pollute global CSS scope
+ * and affect how EUI components are rendered
+ */
+const ignoreInheritedStylesPlugin = () => ({
+    name: 'ignore-styles-plugin',
+    configureWebpack() {
+        return {
+            module: {
+                rules: [
+                    {
+                        test: /node_modules\/infima/,
+                        use: 'null-loader',
+                    },
+                    {
+                        test: /node_modules\/@docusaurus\/theme-common\/lib\/hooks\/styles.css/,
+                        use: 'null-loader',
+                    },
+                ],
+            },
+        };
+    },
+});
+const makePluginConfig = (source, options) => {
+    if (!options) {
+        return require.resolve(source);
+    }
+    return [require.resolve(source), options];
+};
+export default function preset(context, options = {}) {
+    const isProd = process.env.NODE_ENV === 'production';
+    const themes = [
+        // EUI theme is based on the classic docusaurus theme
+        require.resolve('@docusaurus/theme-classic'),
+        require.resolve('@elastic/eui-docusaurus-theme'),
+    ];
+    const plugins = [
+        ignoreInheritedStylesPlugin,
+        makePluginConfig('@docusaurus/plugin-content-docs', options.docs),
+        makePluginConfig('@docusaurus/plugin-content-pages', options.pages),
+        makePluginConfig('@docusaurus/plugin-svgr', options.svgr),
+    ];
+    if (options.blog !== false) {
+        plugins.push(makePluginConfig('@docusaurus/plugin-content-blog', options.blog));
+    }
+    if (isProd) {
+        plugins.push(makePluginConfig('@docusaurus/plugin-sitemap', options.sitemap));
+    }
+    if (options.googleAnalytics) {
+        plugins.push(makePluginConfig('@docusaurus/plugin-google-analytics', options.googleAnalytics));
+    }
+    if (options.googleTagManager) {
+        plugins.push(makePluginConfig('@docusaurus/plugin-google-tag-manager', options.googleTagManager));
+    }
+    if (options.gtag) {
+        plugins.push(makePluginConfig('@docusaurus/plugin-google-gtag', options.gtag));
+    }
+    return { themes, plugins };
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@elastic/eui-docusaurus-preset",
+  "version": "1.0.0",
+  "description": "EUI preset for Docusaurus",
+  "license": "SEE LICENSE IN LICENSE.txt",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "start": "tsc --watch"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/elastic/eui.git",
+    "directory": "packages/docusaurus-preset"
+  },
+  "dependencies": {
+    "@elastic/eui-docusaurus-theme": "^2.0.0"
+  },
+  "devDependencies": {
+    "@docusaurus/types": "^3.7.0",
+    "typescript": "~5.5.4"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,113 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import type {
+  LoadContext,
+  PluginConfig,
+  PluginModule,
+  PluginOptions,
+  Preset,
+} from '@docusaurus/types';
+import { Options } from './options';
+
+/**
+ * Docusaurus plugin to ignore any unwanted style imports, e.g. like Infima stylesheet imports.
+ * This is needed so that Infima doesn't pollute global CSS scope
+ * and affect how EUI components are rendered
+ */
+const ignoreInheritedStylesPlugin: PluginModule = () => ({
+  name: 'ignore-styles-plugin',
+  configureWebpack() {
+    return {
+      module: {
+        rules: [
+          {
+            test: /node_modules\/infima/,
+            use: 'null-loader',
+          },
+          {
+            test: /node_modules\/@docusaurus\/theme-common\/lib\/hooks\/styles.css/,
+            use: 'null-loader',
+          },
+        ],
+      },
+    };
+  },
+});
+
+const makePluginConfig = (
+  source: string,
+  options?: PluginOptions
+): string | [string, PluginOptions] => {
+  if (!options) {
+    return require.resolve(source);
+  }
+
+  return [require.resolve(source), options];
+};
+
+export default function preset(
+  context: LoadContext,
+  options: Options = {}
+): Preset {
+  const isProd = process.env.NODE_ENV === 'production';
+
+  const themes: PluginConfig[] = [
+    // EUI theme is based on the classic docusaurus theme
+    require.resolve('@docusaurus/theme-classic'),
+
+    require.resolve('@elastic/eui-docusaurus-theme'),
+  ];
+
+  const plugins: PluginConfig[] = [
+    ignoreInheritedStylesPlugin,
+    makePluginConfig('@docusaurus/plugin-content-docs', options.docs),
+    makePluginConfig('@docusaurus/plugin-content-pages', options.pages),
+    makePluginConfig('@docusaurus/plugin-svgr', options.svgr),
+  ];
+
+  if (options.blog !== false) {
+    plugins.push(
+      makePluginConfig('@docusaurus/plugin-content-blog', options.blog)
+    );
+  }
+
+  if (isProd) {
+    plugins.push(
+      makePluginConfig('@docusaurus/plugin-sitemap', options.sitemap)
+    );
+  }
+
+  if (options.googleAnalytics) {
+    plugins.push(
+      makePluginConfig(
+        '@docusaurus/plugin-google-analytics',
+        options.googleAnalytics
+      )
+    );
+  }
+
+  if (options.googleTagManager) {
+    plugins.push(
+      makePluginConfig(
+        '@docusaurus/plugin-google-tag-manager',
+        options.googleTagManager
+      )
+    );
+  }
+
+  if (options.gtag) {
+    plugins.push(
+      makePluginConfig('@docusaurus/plugin-google-gtag', options.gtag)
+    );
+  }
+
+  return { themes, plugins };
+}
+
+export type { Options };

package/src/options.ts

@@ -0,0 +1,76 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+// Based on https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-preset-classic/src/options.ts
+
+import type { ThemeConfig as BaseThemeConfig } from '@docusaurus/types';
+import type { UserThemeConfig as ClassicThemeConfig } from '@docusaurus/theme-common';
+
+import type { Options as DocsPluginOptions } from '@docusaurus/plugin-content-docs';
+import type { Options as BlogPluginOptions } from '@docusaurus/plugin-content-blog';
+import type { Options as PagesPluginOptions } from '@docusaurus/plugin-content-pages';
+import type { Options as SitemapPluginOptions } from '@docusaurus/plugin-sitemap';
+import type { Options as SVGRPluginOptions } from '@docusaurus/plugin-svgr';
+import type { Options as ThemeOptions } from '@docusaurus/theme-classic';
+import type { Options as GAPluginOptions } from '@docusaurus/plugin-google-analytics';
+import type { Options as GtagPluginOptions } from '@docusaurus/plugin-google-gtag';
+import type { Options as GTMPluginOptions } from '@docusaurus/plugin-google-tag-manager';
+
+export type Options = {
+  /**
+   * Options for `@docusaurus/plugin-content-docs`.
+   */
+  docs?: DocsPluginOptions;
+
+  /**
+   * Options for `@docusaurus/plugin-content-pages`.
+   */
+  pages?: PagesPluginOptions;
+
+  /**
+   * Options for `@docusaurus/plugin-svgr`.
+   */
+  svgr?: SVGRPluginOptions;
+
+  /**
+   * Options for `@docusaurus/plugin-sitemap`.
+   * Enabled in production builds
+   */
+  sitemap?: SitemapPluginOptions;
+
+  /**
+   * Options for `@docusaurus/theme-classic`.
+   */
+  theme?: ThemeOptions;
+
+  /**
+   * Options for `@docusaurus/plugin-content-blog`.
+   * Use `false` to disable.
+   */
+  blog?: false | BlogPluginOptions;
+
+  /**
+   * Options for `@docusaurus/plugin-google-analytics`. Only enabled when the
+   * key is present.
+   */
+  googleAnalytics?: GAPluginOptions;
+
+  /**
+   * Options for `@docusaurus/plugin-google-gtag`. Only enabled when the key
+   * is present.
+   */
+  gtag?: GtagPluginOptions;
+
+  /**
+   * Options for `@docusaurus/plugin-google-tag-manager`. Only enabled when
+   * the key is present.
+   */
+  googleTagManager?: GTMPluginOptions;
+};
+
+export type ThemeConfig = BaseThemeConfig & ClassicThemeConfig;

package/tsconfig.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "outDir": "lib",
+    /* 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,
+
+    /* 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
+  },
+  "include": ["src"],
+  "exclude": [
+    "node_modules"
+  ]
+}