chore(website): restructure docs folder (2 of 2) #8594

acstll · 2025-04-15T08:28:50Z

Summary

Resolves #8583

Resolves #8576
Resolves #8573

(how do you make this "resolves" one line?)

Following up on #8547 and https://github.com/elastic/eui-private/discussions/282

Scope

Part 2 of #8588, second and last batch of changes to make it easier/faster to review.

The affected folders inside website/docs are:

components
utilities (moved out of getting-started)

Changes

put Utilities in main menu (thank you @tkajtoch) 🆕
eliminate "Category pages" from Components > Forms 🆕
rename content folders and files to use kebab-case e.g. gettings_started/ → getting-started/, color_mode.mdx → color-mode.mdx
rename some overview.mdx files to index.mdx to avoid needed to set the slug explicitly e.g. content/overview.mdx with slug: /content → content/index.md
remove slug and id fields from front matter, leaving that task to Docusaurus' defaults
- update link.id field in _category_.yml with default id, e.g. id: content_writing → id: content/writing/guidelines
adjust sidebar_position and title fields where needed
update Markdown links according to new folder/file names

QA

Visit the affected parts of the site and check:

Navigating the site works as expected
URLs are correct, according to the changes

Important

Pay special attention to Forms, there are no more "Category pages", toggles are plain toggles

Staging links:

weronikaolejniczak

This PR is of high prio and it's amazing you've done it in such a short amount of time! For the future, it'd be great to break it down into smaller PRs or more granular commits because I have to admit, it's hard reviewing and testing everything at once. Once you see the number of files growing, it's best to cut it short.

Great job! 🎉

Testing notes

Designers > Icons redirection is broken:

Redirects to https://eui.elastic.co/pr_8594/new-docs/docs/display/icons, should be https://eui.elastic.co/pr_8594/new-docs/docs/components/display/icons/ instead.

All the highlights links are broken:

They redirect to e.g. https://eui.elastic.co/pr_8594/new-docs/docs/layout/flex, should be https://eui.elastic.co/pr_8594/new-docs/docs/components/layout/flex/.

I didn't notice this change before but Code used to be in Editors and Syntax, and now there's only one element there, "Markdown". Do you think we should move it back, leave it as is?

weronikaolejniczak · 2025-04-15T10:12:01Z

packages/website/docs/components/containers/accordion.mdx

@@ -1,10 +1,7 @@
 ---
-slug: /containers/accordion


non-blocking suggestion:

Personally, I'd prefer to remove the front matter altogether and keep using the h1 Markdown heading. We'd leverage plain Markdown syntax over MDX syntax which is more approachable. Is there a reason why we're moving it to the front matter?

thinking about it more I also prefer the plain markdown syntax

Is there a reason why we're moving it to the front matter?

we were using both and I thought we could make it consistent, then chose the front matter one because it renders with theme/DocItem/Content and also thought it looked better 🤷

I say we follow your suggestion and change this back to plain Markdown

weronikaolejniczak · 2025-04-15T10:14:38Z

packages/website/docs/components/display/icons/index.mdx

@@ -1,12 +1,10 @@
 ---
-slug: /display/icons
-id: display_icons_overview
+title: Icon


non-blocking suggestion:

Maybe we could keep it simple and always name it "Icon" or "Icons"? Whichever is fine.

I think Icons 🤔

weronikaolejniczak · 2025-04-15T10:17:05Z

packages/website/docs/components/index.mdx

 EUI offers a wide variety of components. This section is organized topically with individual pages containing live example, usage recommendations, guidelines, and props.

-The adjacent [patterns](../patterns/) section provies additional guidance for handling use cases that cross multiple components.
+The adjacent [patterns](../patterns/index.mdx) section provies additional guidance for handling use cases that cross multiple components.


Suggested change

The adjacent [patterns](../patterns/index.mdx) section provies additional guidance for handling use cases that cross multiple components.

The adjacent [patterns](../patterns/index.mdx) section provides additional guidance for handling use cases that cross multiple components.

weronikaolejniczak · 2025-04-15T10:20:17Z

packages/website/docs/utilities/scroll/overview.mdx

doubt:

Should this be index.mdx instead?

yes, it should! good catch 🙏

weronikaolejniczak · 2025-04-15T10:22:07Z

packages/website/docs/components/templates/page-template/index.mdx

- **EuiPageTemplate.BottomBar** extends [EuiBottomBar](../../containers/bottom_bar.mdx)
- **EuiPageTemplate.EmptyPrompt** extends [EuiEmptyPrompt](../../display/empty_prompt/index.mdx)
+- **EuiPageTemplate.BottomBar** extends [EuiBottomBar](../../containers/bottom-bar.mdx)
+- **EuiPageTemplate.EmptyPrompt** extends [EuiEmptyPrompt](../../display/empty-prompt/index.mdx)


outside the scope:

Could we fix the formatting in the Demo underneath? Also, there seems to be something breaking syntax highlighting right after this demo. Feel free to skip.

will fix 💅

weronikaolejniczak · 2025-04-15T10:39:40Z

@acstll Let's remember to link #8576 and #8573 as well.

acstll · 2025-04-15T11:12:27Z

thanks a lot @weronikaolejniczak for the great (and super fast as well!) review

broken links are fixed (7e3d878)

I didn't notice this change before but Code used to be in Editors and Syntax, and now there's only one element there, "Markdown". Do you think we should move it back, leave it as is?

@ryankeairns changed this in #8547 (I'd leave it as is)

I'll fix the h1s in a bit and re-request 🌞

acstll · 2025-04-15T11:47:12Z

h1s fixed here aee3e66 😅

elasticmachine · 2025-04-15T11:54:31Z

💚 Build Succeeded

History

💚 Build #67 succeeded 7e3d878
💚 Build #64 succeeded 5e27a7a
💔 Build #62 failed 5d4a8e3

cc @acstll

kibanamachine · 2025-04-15T12:10:31Z

Preview staging links for this PR:

Docs site: https://eui.elastic.co/pr_8594/
Storybook: https://eui.elastic.co/pr_8594/storybook
New docs: https://eui.elastic.co/pr_8594/new-docs

elasticmachine · 2025-04-15T12:12:07Z

💚 Build Succeeded

Buildkite Build
Commit: 90585c8

History

💚 Build #3873 succeeded 7e3d878
💚 Build #3870 succeeded 5e27a7a

cc @acstll

weronikaolejniczak

LGTM! Thanks for tackling this, @acstll 💪🏻

acstll added skip-changelog Use on PRs to skip changelog requirement (Don't delete - used for automation) New EUI site labels Apr 15, 2025

acstll self-assigned this Apr 15, 2025

acstll changed the title ~~chore(website): restructure docs folder (1 of 2)~~ chore(website): restructure docs folder (2 of 2) Apr 15, 2025

acstll added 3 commits April 15, 2025 10:56

feat(website): lift utilities section to main menu

9414000

chore(website): restructure components folder

1c1983c

fix(website): broken links in pagination page

5e27a7a

acstll force-pushed the chore/docs-post-ai-2 branch from 8a675d1 to 5e27a7a Compare April 15, 2025 08:57

acstll marked this pull request as ready for review April 15, 2025 09:21

acstll requested a review from a team as a code owner April 15, 2025 09:21

weronikaolejniczak self-requested a review April 15, 2025 09:24

weronikaolejniczak requested changes Apr 15, 2025

View reviewed changes

acstll added 4 commits April 15, 2025 12:56

chore(website): demo formatting

ec7eedf

fix(website): scroll page filename

903bb7f

fix(website): typo

07c2d09

fix(website): broken links in homepage

7e3d878

acstll added 2 commits April 15, 2025 13:39

chore(website): markdown for h1 everywhere

aee3e66

fix(website): broken link

90585c8

acstll requested a review from weronikaolejniczak April 15, 2025 11:46

weronikaolejniczak approved these changes Apr 15, 2025

View reviewed changes

acstll merged commit e327dbb into elastic:main Apr 15, 2025
6 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore(website): restructure docs folder (2 of 2) #8594

chore(website): restructure docs folder (2 of 2) #8594

acstll commented Apr 15, 2025 •

edited

Loading

weronikaolejniczak left a comment •

edited

Loading

weronikaolejniczak Apr 15, 2025

acstll Apr 15, 2025

weronikaolejniczak Apr 15, 2025

acstll Apr 15, 2025

weronikaolejniczak Apr 15, 2025

acstll Apr 15, 2025

weronikaolejniczak Apr 15, 2025

acstll Apr 15, 2025

weronikaolejniczak Apr 15, 2025 •

edited

Loading

acstll Apr 15, 2025

weronikaolejniczak commented Apr 15, 2025

acstll commented Apr 15, 2025

acstll commented Apr 15, 2025

elasticmachine commented Apr 15, 2025

kibanamachine commented Apr 15, 2025

elasticmachine commented Apr 15, 2025

weronikaolejniczak left a comment

	The adjacent [patterns](../patterns/index.mdx) section provies additional guidance for handling use cases that cross multiple components.
	The adjacent [patterns](../patterns/index.mdx) section provides additional guidance for handling use cases that cross multiple components.

chore(website): restructure docs folder (2 of 2) #8594

chore(website): restructure docs folder (2 of 2) #8594

Conversation

acstll commented Apr 15, 2025 • edited Loading

Summary

Scope

Changes

QA

weronikaolejniczak left a comment • edited Loading

Choose a reason for hiding this comment

Testing notes

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

weronikaolejniczak Apr 15, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

weronikaolejniczak commented Apr 15, 2025

acstll commented Apr 15, 2025

acstll commented Apr 15, 2025

elasticmachine commented Apr 15, 2025

💚 Build Succeeded

History

kibanamachine commented Apr 15, 2025

elasticmachine commented Apr 15, 2025

💚 Build Succeeded

History

weronikaolejniczak left a comment

Choose a reason for hiding this comment

acstll commented Apr 15, 2025 •

edited

Loading

weronikaolejniczak left a comment •

edited

Loading

weronikaolejniczak Apr 15, 2025 •

edited

Loading