Skip to content

Improve Navigation Menu Readability with Shortened Labels & Tooltips #169

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
chiztechnology wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Improve Navigation Menu Readability with Shortened Labels & Tooltips #169

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions website/docs/how-to-guide/_category_.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
label: How To Guide
label: How-To
Copy link
Contributor

@Ranchhand87 Ranchhand87 Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe a question for the DA's is this a single page to explain the site, or something that linkes to multiple guides? Maybe it would read How-To's in the latter example.

position: 10
link:
type: generated-index
type: generated-index
customProps:
full_name: How To Guide
4 changes: 3 additions & 1 deletion website/docs/maintainer-retainer/_category_.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,2 +1,4 @@
label: Maintainer Retainer Program (MRP)
Copy link
Contributor

@Ranchhand87 Ranchhand87 Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a program under the Paid Open Source Model (POSM), The OSC might need to weigh in when it comes to reducing the Title.

If there were multiple maintainer programs, that would make sense to reduce, otherwise while the focus is retained on MRP, I am not sure that this should change, Maybe the page needs to move?

Copy link
Author

@chiztechnology chiztechnology Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That makes sense.

My goal with the change was purely to improve sidebar readability and layout consistency, especially on smaller screens. There was no intention to reduce the formal identity or visibility of the Maintainer Retainer Program (MRP).

Given that this falls under POSM governance and may carry formal significance, I completely understand that shortening the title could introduce ambiguity.

I Can:

• Revert the Maintainer Retainer Program (MRP) title change,
• Keep the full official name in the sidebar,
• Or explore alternative UX approaches (e.g., restructuring navigation, moving the page, or CSS-only truncation without renaming)

Please let me know the preferred direction, and I’ll adjust accordingly.

Copy link
Member

@danbaruka danbaruka Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would suggest exploring UX improvements and CSS-only solutions if possible. That way, the full official title remains intact and we avoid any wording changes that could alter the context or formal meaning.

Copy link
Contributor

@Ranchhand87 Ranchhand87 Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would like the DA's to weigh in. Originally this is here as there was drafting for CONTRIBUTING.md changes related to MRP. There are likely other POSM programs that should have suggested documentation updates and thus be listed here on devex.

I value your contribution, Thanks!

Just noting that some gaps should be addressed when we find them, as opposed to making small fixes that have to be done iteratively.

label: Maintainer Program
position: 3
customProps:
full_name: Maintainer Retainer Program (MRP)
4 changes: 3 additions & 1 deletion website/docs/working-group/_category_.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
label: Developer Experience Working Group
label: Dev Experience WG
Copy link
Contributor

@Ranchhand87 Ranchhand87 Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As is common with other references, If one is shortened, so the other should be too. EX: Dev Ex

position: 30
link:
type: doc
id: readme
customProps:
full_name: Developer Experience Working Group
2 changes: 1 addition & 1 deletion website/package-lock.json
View file
Open in desktop
Copy link
Member

@danbaruka danbaruka Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @chiztechnology
Kindly ensure that package-lock.json or yarn.lock is not part of your changes unless there is a specific reason to update it.

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

70 changes: 70 additions & 0 deletions website/src/css/custom.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -449,6 +449,76 @@
color: #999999 !important;
}

/* Text truncation and resize improvements - Menu items */
.menu__link {
max-width: 100%;
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
display: flex;
align-items: center;
}

/* Ensure label text respects max-width */
.menu__link span {
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
}

/* Tooltip styling - display full text on hover */
.menu__link[title]:hover::after,
.menu__list-item-collapsible .menu__link[title]:hover::after {
content: attr(title);
position: absolute;
background-color: #333333;
color: #ffffff;
padding: 0.5rem 0.75rem;
border-radius: 4px;
font-size: 0.8rem;
white-space: normal;
width: auto;
max-width: 200px;
left: 100%;
top: 0;
margin-left: 0.5rem;
z-index: 1000;
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
pointer-events: none;
}

/* Tooltip styling for dark mode */
[data-theme='dark'] .menu__link[title]:hover::after,
[data-theme='dark'] .menu__list-item-collapsible .menu__link[title]:hover::after {
background-color: #666666;
color: #ffffff;
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.5);
}

/* Arrow pointer for tooltip */
.menu__link[title]:hover::before,
.menu__list-item-collapsible .menu__link[title]:hover::before {
content: '';
position: absolute;
border: 5px solid transparent;
border-right-color: #333333;
left: calc(100% - 5px);
top: 50%;
transform: translateY(-50%);
z-index: 1001;
}

[data-theme='dark'] .menu__link[title]:hover::before,
[data-theme='dark'] .menu__list-item-collapsible .menu__link[title]:hover::before {
border-right-color: #666666;
}

/* Menu item positioning for tooltip display */
.menu__list-item-collapsible,
.menu__list-item {
position: relative;
}

/* Nested menu items - thin font, maintain gray color for inactive nested items */
.menu__list .menu__list-item .menu__link {
color: #404040 !important;
Expand Down
24 changes: 24 additions & 0 deletions website/src/theme/Root.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,27 @@ export default function Root({ children }) {
const siteUrl = siteConfig.url;

useEffect(() => {
// Tooltip mappings for shortened menu items
const tooltipMap = {
"Dev Experience WG": "Developer Experience Working Group",
"Maintainer Program": "Maintainer Retainer Program (MRP)",
"How-To": "How To Guide",
};

// Add title attributes to menu items for tooltip display
const addMenuTooltips = () => {
const menuLinks = document.querySelectorAll(".menu__link, .menu__link--sublist");
menuLinks.forEach((link) => {
const text = link.textContent?.trim();
if (text && tooltipMap[text] && !link.getAttribute("title")) {
link.setAttribute("title", tooltipMap[text]);
}
});
};

// Initial call
addMenuTooltips();

// Minimal MutationObserver to fix any black text in search dropdown that CSS might miss
const observer = new MutationObserver(() => {
const darkTheme = document.documentElement.getAttribute("data-theme") === "dark";
Expand All @@ -28,6 +49,9 @@ export default function Root({ children }) {
});
});
}

// Add tooltips to newly rendered menu items
addMenuTooltips();
});

observer.observe(document.body, {
Expand Down
33 changes: 14 additions & 19 deletions website/yarn.lock
View file
Open in desktop
Copy link
Member

@danbaruka danbaruka Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Kindly ensure that package-lock.json or yarn.lock is not part of your changes unless there is a specific reason to update it.

Original file line number Diff line number Diff line change
Expand Up @@ -2027,7 +2027,7 @@

"@easyops-cn/docusaurus-search-local@^0.55.0":
version "0.55.0"
resolved "https://registry.yarnpkg.com/@easyops-cn/docusaurus-search-local/-/docusaurus-search-local-0.55.0.tgz#43bfa82983ae6d0291036ce5b415f55a6fc92170"
resolved "https://registry.npmjs.org/@easyops-cn/docusaurus-search-local/-/docusaurus-search-local-0.55.0.tgz"
integrity sha512-pmyG+e9KZmo4wrufsneeoE2KG2zH9tbRGi0crJFY0kPxOTGSLeuU5w058Qzgpz8vZNui6i59lKjrlQtnXNBgog==
dependencies:
"@docusaurus/plugin-content-docs" "^2 || ^3"
Expand Down Expand Up @@ -2363,10 +2363,10 @@
resolved "https://registry.npmjs.org/@noble/hashes/-/hashes-1.4.0.tgz"
integrity sha512-V1JJ1WTRUqHHrOSh597hURcMqVKVGL/ea3kv0gSnEdsEZ0/+VyPghM1lMNGc00z7CIQorSvbKpuJkxvuHbvdbg==

"@node-rs/jieba-darwin-arm64@1.10.4":
"@node-rs/jieba-win32-x64-msvc@1.10.4":
version "1.10.4"
resolved "https://registry.npmjs.org/@node-rs/jieba-darwin-arm64/-/jieba-darwin-arm64-1.10.4.tgz"
integrity sha512-G++RYEJ2jo0rxF9626KUy90wp06TRUjAsvY/BrIzEOX/ingQYV/HjwQzNPRR1P1o32a6/U8RGo7zEBhfdybL6w==
resolved "https://registry.npmjs.org/@node-rs/jieba-win32-x64-msvc/-/jieba-win32-x64-msvc-1.10.4.tgz"
integrity sha512-+sqemSfS1jjb+Tt7InNbNzrRh1Ua3vProVvC4BZRPg010/leCbGFFiQHpzcPRfpxAXZrzG5Y0YBTsPzN/I4yHQ==

"@node-rs/jieba@^1.6.0":
version "1.10.4"
Expand Down Expand Up @@ -4481,7 +4481,7 @@ cytoscape-fcose@^2.2.0:
dependencies:
cose-base "^2.2.0"

cytoscape@^3.29.3:
cytoscape@^3.2.0, cytoscape@^3.29.3:
version "3.33.1"
resolved "https://registry.npmjs.org/cytoscape/-/cytoscape-3.33.1.tgz"
integrity sha512-iJc4TwyANnOGR1OmWhsS9ayRS3s+XQ185FmuHObThD+5AeJCakAAbWv8KimMTt08xCCLNgneQwFp+JRJOr9qGQ==
Expand Down Expand Up @@ -5529,11 +5529,6 @@ fs-extra@^11.1.1, fs-extra@^11.2.0:
jsonfile "^6.0.1"
universalify "^2.0.0"

fsevents@~2.3.2:
version "2.3.3"
resolved "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz"
integrity sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==

function-bind@^1.1.2:
version "1.1.2"
resolved "https://registry.npmjs.org/function-bind/-/function-bind-1.1.2.tgz"
Expand Down Expand Up @@ -6921,7 +6916,7 @@ merge2@^1.3.0, merge2@^1.4.1:
resolved "https://registry.npmjs.org/merge2/-/merge2-1.4.1.tgz"
integrity sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg==

mermaid@>=11.6.0, mermaid@^11.12.3:
mermaid@^11.12.3, mermaid@>=11.6.0:
version "11.12.3"
resolved "https://registry.npmjs.org/mermaid/-/mermaid-11.12.3.tgz"
integrity sha512-wN5ZSgJQIC+CHJut9xaKWsknLxaFBwCPwPkGTSUYrTiHORWvpT8RxGk849HPnpUAQ+/9BPRqYb80jTpearrHzQ==
Expand Down Expand Up @@ -8630,9 +8625,9 @@ rc@1.2.8:
minimist "^1.2.0"
strip-json-comments "~2.0.1"

react-dom@^19.2.4:
react-dom@*, "react-dom@^16.14.0 || 17 || ^18 || ^19", "react-dom@^16.6.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", "react-dom@^18.0.0 || ^19.0.0", react-dom@^19.2.4, "react-dom@>= 16.8.0 < 20.0.0":
version "19.2.4"
resolved "https://registry.yarnpkg.com/react-dom/-/react-dom-19.2.4.tgz#6fac6bd96f7db477d966c7ec17c1a2b1ad8e6591"
resolved "https://registry.npmjs.org/react-dom/-/react-dom-19.2.4.tgz"
integrity sha512-AXJdLo8kgMbimY95O2aKQqsz2iWi9jMgKJhRBAxECE4IFxfcazB2LmzloIoibJI3C12IlY20+KFaLv+71bUJeQ==
dependencies:
scheduler "^0.27.0"
Expand Down Expand Up @@ -8712,9 +8707,9 @@ react-router@^5.3.4, react-router@>=5, react-router@5.3.4:
tiny-invariant "^1.0.2"
tiny-warning "^1.0.0"

react@^19.2.4:
react@*, "react@^16.14.0 || ^17 || ^18 || ^19", "react@^16.6.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", "react@^18.0.0 || ^19.0.0", react@^19.2.4, "react@>= 16.8.0 < 20.0.0", react@>=15, react@>=16, react@>=16.0.0:
version "19.2.4"
resolved "https://registry.yarnpkg.com/react/-/react-19.2.4.tgz#438e57baa19b77cb23aab516cf635cd0579ee09a"
resolved "https://registry.npmjs.org/react/-/react-19.2.4.tgz"
integrity sha512-9nfp2hYpCwOjAN+8TZFGhtWEwgvWHXqESH8qT89AT/lWklpLON22Lc8pEtnpsZz7VmawabSU0gCjnj8aC0euHQ==

readable-stream@^2.0.1:
Expand Down Expand Up @@ -9059,7 +9054,7 @@ rw@1:
resolved "https://registry.npmjs.org/rw/-/rw-1.3.3.tgz"
integrity sha512-PdhdWy89SiZogBLaw42zdeqtRJ//zFd2PgQavcICDUgJT5oW10QCRKbJ6bg4r0/UY2M6BWd5tkxuGFRvCkgfHQ==

safe-buffer@5.2.1, safe-buffer@>=5.1.0, safe-buffer@^5.1.0, safe-buffer@~5.2.0:
safe-buffer@^5.1.0, safe-buffer@>=5.1.0, safe-buffer@~5.2.0, safe-buffer@5.2.1:
version "5.2.1"
resolved "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.2.1.tgz"
integrity sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ==
Expand All @@ -9081,7 +9076,7 @@ sax@^1.2.4:

scheduler@^0.27.0:
version "0.27.0"
resolved "https://registry.yarnpkg.com/scheduler/-/scheduler-0.27.0.tgz#0c4ef82d67d1e5c1e359e8fc76d3a87f045fe5bd"
resolved "https://registry.npmjs.org/scheduler/-/scheduler-0.27.0.tgz"
integrity sha512-eNv+WrVbKu1f3vbYJT/xtiF5syA5HPIMtf9IgY/nKg0sWqzAUEvqY/xm7OcZc/qafLx/iO9FgOmeSAp4v5ti/Q==

schema-dts@^1.1.2:
Expand Down Expand Up @@ -9754,9 +9749,9 @@ typedarray-to-buffer@^3.1.5:
dependencies:
is-typedarray "^1.0.0"

typescript@~5.9.3:
typescript@>=2.7, typescript@>=4.9.5, typescript@~5.9.3:
version "5.9.3"
resolved "https://registry.yarnpkg.com/typescript/-/typescript-5.9.3.tgz#5b4f59e15310ab17a216f5d6cf53ee476ede670f"
resolved "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz"
integrity sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==

ufo@^1.6.1:
Expand Down