Skip to content

Commit e46ba63

Browse files
weronikaolejniczaktsullivan
weronikaolejniczak
authored and
tsullivan
committed
Docusaurus theme updates for release (#8814)
1 parent 6006af7 commit e46ba63

File tree

88 files changed

+2025
-221
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

88 files changed

+2025
-221
lines changed

‎packages/docusaurus-preset/LICENSE.txt‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Source code in this repository is covered by (i) a dual license under the Server
2+
Side Public License, v 1 and the Elastic License 2.0 or (ii) an Apache License
3+
2.0 compatible license or (iii) solely under the Elastic License 2.0, in each
4+
case, as noted in the applicable header. The default throughout the repository
5+
is a dual license under the Server Side Public License, v 1 and the Elastic
6+
License 2.0, unless the header specifies another license.

‎packages/docusaurus-preset/README.md‎

Lines changed: 214 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,216 @@
11
# `@elastic/eui-docusaurus-preset`
22

3+
EUI custom [Docusaurus](https://docusaurus.io/) preset made for the EUI [documentation website](https://eui.elastic.co).
4+
5+
## Overview
6+
7+
The preset comes with themes and plugins configured.
8+
9+
### Themes
10+
11+
| Theme | Description |
12+
|---------------------------------|----------------------------------------------------|
13+
| `@docusaurus/theme-classic` | Base Docusaurus theme (required for compatibility) |
14+
| `@elastic/eui-docusaurus-theme` | EUI custom theme for Docusaurus |
15+
16+
### Plugins
17+
18+
| Plugin | Description. | Enabled by default? |
19+
|----------------------------------------|---------------------------------------------------------------------|---------------------------|
20+
| `ignore-styles-plugin` | Prevents Infima and some inherited styles from polluting global CSS | Yes |
21+
| `@docusaurus/plugin-content-docs` | Documentation pages support | Yes (configurable) |
22+
| `@docusaurus/plugin-content-pages` | Static pages support | Yes (configurable) |
23+
| `@docusaurus/plugin-svgr` | SVG import support | Yes (configurable) |
24+
| `@docusaurus/plugin-content-blog` | Blog support | Yes (configurable) |
25+
| `@docusaurus/plugin-sitemap` | Sitemap generation (for SEO) | Only in production builds |
26+
| `@docusaurus/plugin-google-analytics` | Google Analytics integration | If configured |
27+
| `@docusaurus/plugin-google-tag-manager`| Google Tag Manager integration | If configured |
28+
| `@docusaurus/plugin-google-gtag` | Google Global Site Tag integration | If configured |
29+
30+
## Usage
31+
32+
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.
33+
34+
To use it in your Docusaurus project, install the package:
35+
36+
```shell
37+
# npm
38+
npm install @elastic/eui-docusaurus-preset
39+
40+
# pnpm
41+
pnpm add @elastic/eui-docusaurus-preset
42+
43+
# Yarn
44+
yarn add @elastic/eui-docusaurus-preset
45+
```
46+
47+
and in your `docusaurus.config.ts` file, add:
48+
49+
```ts
50+
const config: Config = {
51+
// ...
52+
presets: [
53+
[
54+
require.resolve("@elastic/eui-docusaurus-preset"),
55+
{
56+
docs: {
57+
sidebarPath: "./sidebars.ts",
58+
},
59+
} satisfies Preset.Options,
60+
],
61+
],
62+
// ...
63+
}
64+
```
65+
66+
### Theme only
67+
68+
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.
69+
70+
If you prefer to use only the theme, refer to [Theme only](../docusaurus-theme/README.md#theme-only) section in `@elastic/eui-docusaurus-theme`.
71+
72+
## Local development
73+
74+
### Prerequisites
75+
76+
This package requires:
77+
78+
- Node.js (check current version in [.nvmrc](../../.nvmrc)),
79+
- [corepack](https://nodejs.org/api/corepack.html).
80+
81+
### Installing dependencies
82+
83+
Please run `yarn` to install dependencies:
84+
85+
```shell
86+
yarn
87+
```
88+
89+
### Building the package
90+
91+
```shell
92+
yarn build
93+
```
94+
95+
### Building in watch mode
96+
97+
Run the following command to build this package whenever a file is edited:
98+
99+
```shell
100+
yarn start
101+
```
102+
103+
:::warning
104+
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.
105+
106+
If that's the case please run `yarn build`.
107+
:::
108+
109+
### Test with EUI documentation website
110+
111+
Run the following command from the root of the mono-repository to run the website:
112+
113+
```shell
114+
yarn workspace @elastic/eui-website start
115+
```
116+
117+
You can pair it with the watch mode when modifying the Docusaurus theme.
118+
119+
### Test locally with your own Docusaurus project
120+
121+
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).
122+
123+
Run the following command to create a Docusaurus project:
124+
125+
```shell
126+
npx create-docusaurus@latest my-website classic --typescript
127+
```
128+
129+
Install `yalc` globally if you haven't already:
130+
131+
```shell
132+
npm install -g yalc
133+
```
134+
135+
In the root of the mono-repository, run the following commands to build and publish the preset locally:
136+
137+
```shell
138+
yarn workspace @elastic/eui-docusaurus-preset build
139+
140+
# Publish the preset locally
141+
cd packages/docusaurus-preset
142+
yalc publish
143+
```
144+
145+
In your project, install EUI dependencies:
146+
147+
```shell
148+
# npm
149+
npm install @elastic/eui @elastic/charts @emotion/react @emotion/css moment
150+
151+
# pnpm
152+
pnpm add @elastic/eui @elastic/charts @emotion/react @emotion/css moment
153+
154+
# Yarn
155+
yarn add @elastic/eui @elastic/charts @emotion/react @emotion/css moment
156+
```
157+
158+
and add the locally published packages:
159+
160+
```shell
161+
yalc add @elastic/eui-docusaurus-preset
162+
163+
# npm
164+
npm install
165+
166+
# pnpm
167+
pnpm install
168+
169+
# Yarn
170+
yarn
171+
```
172+
173+
Configure Docusaurus to use the locally built preset as outlined in the [Usage section](#usage).
174+
175+
#### Making changes
176+
177+
When you make changes to the preset, rebuild and republish the packages:
178+
179+
```shell
180+
# From the mono-repository root
181+
yarn workspace @elastic/eui-docusaurus-preset build
182+
183+
cd packages/docusaurus-preset
184+
yalc publish --push
185+
```
186+
187+
The `--push` flag automatically updates all projects using these packages.
188+
189+
Restart your Docusaurus development server:
190+
191+
```shell
192+
# npm
193+
npm run start
194+
195+
# pnpm
196+
pnpm start
197+
198+
# Yarn
199+
yarn start
200+
```
201+
202+
When you're done testing, remove the locally published packages from your project:
203+
204+
```shell
205+
# In your project
206+
yalc remove @elastic/eui-docusaurus-preset
207+
208+
# npm
209+
npm install
210+
211+
# pnpm
212+
pnpm install
213+
214+
# Yarn
215+
yarn
216+
```

‎packages/docusaurus-preset/package.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
{
22
"name": "@elastic/eui-docusaurus-preset",
3+
"version": "1.0.0",
34
"description": "EUI preset for Docusaurus",
5+
"license": "SEE LICENSE IN LICENSE.txt",
46
"main": "lib/index.js",
57
"types": "lib/index.d.ts",
68
"scripts": {
@@ -12,6 +14,9 @@
1214
"url": "https://github.com/elastic/eui.git",
1315
"directory": "packages/docusaurus-preset"
1416
},
17+
"dependencies": {
18+
"@elastic/eui-docusaurus-theme": "workspace:^"
19+
},
1520
"devDependencies": {
1621
"@docusaurus/types": "^3.7.0",
1722
"typescript": "~5.5.4"

‎packages/docusaurus-theme/LICENSE.txt‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Source code in this repository is covered by (i) a dual license under the Server
2+
Side Public License, v 1 and the Elastic License 2.0 or (ii) an Apache License
3+
2.0 compatible license or (iii) solely under the Elastic License 2.0, in each
4+
case, as noted in the applicable header. The default throughout the repository
5+
is a dual license under the Server Side Public License, v 1 and the Elastic
6+
License 2.0, unless the header specifies another license.

‎packages/docusaurus-theme/NOTICE.txt‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
@elastic/eui-docusaurus-theme
2+
Copyright 2024-2025 Elasticsearch B.V.
3+
4+
---
5+
6+
This product bundles code based on @docusaurus/theme-classic which is
7+
available under a "MIT" license.
8+
9+
MIT License
10+
11+
Copyright (c) Facebook, Inc. and its affiliates.
12+
13+
Permission is hereby granted, free of charge, to any person obtaining a copy
14+
of this software and associated documentation files (the "Software"), to deal
15+
in the Software without restriction, including without limitation the rights
16+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
17+
copies of the Software, and to permit persons to whom the Software is
18+
furnished to do so, subject to the following conditions:
19+
20+
The above copyright notice and this permission notice shall be included in all
21+
copies or substantial portions of the Software.
22+
23+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
24+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
25+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
26+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
27+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
28+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
29+
SOFTWARE.

0 commit comments

Comments
 (0)