Nav Button Highlighter component - now working

Drew-ART · November 18, 2025, 1:14pm

I had to rebuild it as a purely CSS component as i had issues getting the admin section of the Javascript version stable, which means you have to edit the CSS selectors directly to make it work on your site.

The aim of the component is to help you highlight a path you specifically want users to take.

Link: https://github.com/focallocal/nav-buttons-highlighter

Here it is installed and highlighting the Kanban board plugin which most users on my platform would not know where to find after being members for months, especially those who mostly use mobile.

Desktop:

Mobile:

# Nav Buttons Highlighter

A Discourse theme component that highlights navigation buttons to guide users toward specific paths or functions you want them to follow, and makes the mobile dropdown menu more clear and visible.

Purpose

This component helps you:

Guide users by highlighting important navigation links (e.g., your task board, documentation, or key categories)
Improve mobile UX by making the dropdown navigation button stand out
Create visual hierarchy in your navigation bar

Features

Clean button styling with solid colors and hover effects
Admin configurable - no CSS editing required
Support for up to 3 custom navigation buttons
Mobile-responsive - includes mobile dropdown button highlighting
Pre-configured for Discourse Kanban plugin by default
Color picker support for easy customization

Default Configuration

By default, this component is set up to highlight the Discourse Kanban plugin (link) in BLUE (#4285F4).

Installation

In the Discourse Admin console, go to Customize → Themes → Components and click Install

Copy from Git repository link and paste:

https://github.com/focallocal/nav-buttons-highlighter

Once installed, add the component to your active theme.

How to Customize

Admin Settings Panel

All configuration is done through simple admin settings - no CSS editing required!

To configure:

Go to Admin → Customize → Themes
Click on your active theme
Find Nav Buttons Highlighter in the Included Components section
Click Settings

Available Settings:

Button 1 - Kanban (Default):

Highlight Kanban: Toggle on/off (default: on)
Kanban Color: Color picker (default: blue #4285F4)
Kanban Selector: CSS selector (default: a.kanban-nav)

Button 2 - Custom:

Highlight Button 2: Enable second button (default: off)
Button 2 Color: Color picker (default: green #4CAF50)
Button 2 Selector: Enter your CSS selector (e.g., a[href='/page'])

Button 3 - Custom:

Highlight Button 3: Enable third button (default: off)
Button 3 Color: Color picker (default: orange #FF5722)
Button 3 Selector: Enter your CSS selector

Mobile:

Highlight Mobile Dropdown: Toggle mobile Latest dropdown (default: on)
Mobile Dropdown Color: Color picker (default: blue #4285F4)

Finding CSS Selectors:

To highlight different navigation links, you need their CSS selector:

Open your forum in a browser
Right-click the link you want to highlight
Select “Inspect Element”
Look for the <a> tag and note:
- Class names: class="kanban-nav" → use: a.kanban-nav
- Href value: href="/c/support" → use: a[href="/c/support"]

Common Examples:

Kanban plugin: a.kanban-nav
Support category: a[href="/c/support"]
Documentation tag: a[href="/tags/documentation"]
Custom page: a[href="/my-page"]
Second nav button: #navigation-bar > li:nth-child(2) > a

Color Selection:

Use hex color codes (e.g., #4285F4 for blue). The component automatically generates:

Lighter shade for top of gradient
Darker shade for bottom/shadow
Hover and active state colors

Popular Colors:

Blue: #4285F4 (default)
Green: #4CAF50
Red: #F44336
Orange: #FF9800
Purple: #9C27B0

Stable CSS-Only Version

If you prefer direct CSS editing, the previous version (2.0.1) is available:

Install the CSS-only version:

https://github.com/focallocal/nav-buttons-highlighter/tree/stable-v2.0.1

See that branch’s README for CSS editing instructions.

Development

This repository contains:

common/common.scss — All button styling and detailed customization guide
assets/javascripts/discourse/api-initializers/nav-buttons-highlighter.js — Minimal initializer (required for Discourse)
about.json — Component metadata

Troubleshooting

Q: Changes aren’t appearing
A: After editing, click “Save” and hard-refresh your forum page (Ctrl+F5 or Cmd+Shift+R).

Q: I want to highlight multiple buttons
A: Copy the entire button CSS block and paste it underneath the existing CSS rule, then change the selector and optionally the colors.

License

MIT — Public Happiness Movement

merefield · November 18, 2025, 1:25pm

Nice.

but what’s with all the strange markdown?

have you flagged to move it to Theme component ?

Drew-ART · November 18, 2025, 1:33pm

Thanks

I copy/pasted directly from the Github readme, i didn’t see that i needed to click the toggle to put markdown in here. I’ve been editing it since clicking post.

have you flagged to move it to Theme component ?

No, wanted to get feedback and check it was all ok first.

Drew-ART · November 18, 2025, 1:47pm

I had a bizarre issue where Discourse cached a corrupt file, i think it was the about.json file and every edit i made to it failed to update or re-install. Took forever to work out why i couldn’t get any change to build at all.

Is there a better way to test a component rather than on a live site?

For anyone having that issue in the future it shows as a ‘500 error’ when installing and the /logs sections points to the about.json file as the culprit, and was fixed by creating a new github repo for it with a different name and also bumping the version by a whole digit (1.01 to 2.0.1), which made Discourse treat it as a new component.

Persistent 500 errors when trying to install/update a theme component.
The error was “invalid byte sequence in UTF-8” in version.rb during git import.

ROOT CAUSE:

Discourse caches theme repository metadata during import
When our component had a corrupted .discourse-compatibility file or malformed about.json,
Discourse cached this error state
Even after fixing the files and pushing updates, the cache persisted the error

SOLUTION:

Changed component name in about.json (e.g., “Theme Name” → “Theme Name Fresh”)
Bumped major version (1.0.0 → 2.0.0)
This forced Discourse to treat it as a new component and bypass the cached error

PREVENTION:

Always validate JSON files before committing (use jsonlint or VS Code validation)
Ensure all files use UTF-8 encoding without BOM
Delete .discourse-compatibility if not needed (minimum_discourse_version in about.json is sufficient)
If you get persistent import errors, try bumping the version number or temporarily renaming the component

NateDhaliwal · November 19, 2025, 2:44am

@Drew-ART Have you looked at Objects type for theme setting? Perhaps then it can be used to add many CSS rules, perhaps using nesting to add things like background color and padding to each rule. SCSS has a each loop that you may be able to use.

Perhaps this may help?

github.com/Arkshine/discourse-banner-featured-links

scss/functions.scss

ce190f66a


      
            @return $result;
          }
          
          /**
           * Parses a string of ruby-like key-value pairs into a map.
           * Format: [{"key1"=>"value1", "key2"=>"value2"}, {"key1"=>"value1","key2"=>"value2"}]
           *
           * @param {String} $string - The string of key-value pairs.
           * @return {Map} - The map of key-value pairs.
           */
          @function parseObjectSettings($string) {
            $string: str-slice($string, 2, -2);
            $items: str-split($string, "}, {");
          
            $parsedItems: ();
          
            @each $item in $items {
              $item: str-replace($item, "{", "");
              $item: str-replace($item, "}", "");
              $item: str-trim($item);

Drew-ART · November 19, 2025, 12:47pm

Thank @NateDhaliwal. That was my original approach but i ran into the 500 error above and couldn’t get past it for ages, so i returned to a CSS only approach.

I could revert back to that abandoned attempt and see if it loads now i think i have a handle on the 500 error. I’ll give it a go.

Drew-ART · November 19, 2025, 1:28pm

No, can’t get that working at all.

I set it with admin settings and falling back to CSS if they don’t load correctly, but something i can’t catch stops it from working entirely.

Drew-ART · November 19, 2025, 9:13pm

(post deleted by author)

Drew-ART · November 20, 2025, 12:36am

Ok i got the admin section working using simple text/boolean settings.

I found it difficult to get it working the Objects type with SCSS parsing and would love to hear from anyone who can explain why the branch above didn’t work, but anyone wanting to use it now can customise their settings in the component admin section now.

Topic		Replies	Views
First component attempt. I've had a go at creating a Nav Button Highlighter. Not working as yet Dev	1	45	November 11, 2025
Highlighter Composer Button Theme component	22	1301	September 5, 2023
Composer Highlighted Button Theme component	6	665	October 21, 2025
Fast Highlight Dev	49	2304	September 30, 2023
MD Composer extras Theme component	70	8697	July 8, 2025