feat: documentation page deep linking and UI cleanup #2289

tonybentley · 2026-01-24T05:49:45Z

Summary

Deep linking: Browser URL syncs bidirectionally with iframe navigation (path + anchor fragments), enabling shareable doc links and browser back/forward
Layout: Auto-close sidebar on docs page, suppress container padding for full-width content
Toolbar branding: Show Signal K logo standalone, home icon when embedded in Admin UI iframe

Standalone — Signal K logo

Embedded in Admin UI — home icon

Test plan

Navigate to /admin/#/documentation — sidebar closes, no excess margins
Click doc links in iframe — browser URL updates
Paste deep link URL — correct page loads in iframe
Browser back/forward — iframe navigates accordingly
Anchor links sync hash to URL
Standalone /documentation/ — Signal K logo displayed
Embedded in Admin UI — home icon replaces logo
Click home icon — navigates to doc index

Closes #2282

🤖 Generated with Claude Code

Auto-close sidebar on mount, suppress container padding for /documentation routes, and sync iframe navigation bidirectionally with browser URL (including anchor fragments via hashchange listener). Closes SignalK#2282 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Detect iframe context via inline script, toggle CSS classes to show Signal K logo in standalone mode and a home icon when embedded in the Admin UI. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

dirkwa · 2026-01-24T07:14:14Z

Is it back again that once you accidentally clicked it on the sidebar that there is no human understandably easy way back as before 2.20.0 and you wish the entire product to hell and burn there till infinity?

The useEffect that hides the sidebar on mount now cleans up on unmount, ensuring the sidebar reappears when the user leaves via back button, sidebar link, or any route change. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

tonybentley · 2026-01-24T17:28:51Z

@dirkwa

This is covered by the acceptance criteria:

Given I am on the Documentation page with the sidebar auto-closed
When I navigate away via any mechanism (browser back button, clicking a sidebar link, or any route change)
Then the Admin UI sidebar MUST be restored to its visible state

dirkwa · 2026-01-24T19:17:17Z

So trapped again as before 😢.
I instantly dislike 👎 it.

Not that your code is bad or tht you went to help, but this usabillity is horrible.

dirkwa · 2026-01-24T19:21:57Z

Here is more background to this.

https://discord.com/channels/1170433917761892493/1170434656877948928/1458996432123199694

dirkwa · 2026-01-24T19:24:02Z

What about just not collapsing the sidebar?
This would help big time.

tonybentley · 2026-01-24T21:59:43Z

So trapped again as before 😢. I instantly dislike 👎 it.

Not that your code is bad or tht you went to help, but this usabillity is horrible.

Seems like you're confused. Checkout this branch and test it. Then provide feedback

dirkwa · 2026-01-24T22:05:07Z

Fair enough - I looked at your provided screenshot where only documentation is in full screen and overlays everything is visible.
That breaks the nice UI with the side bar. If you have seen discord than there was a plan to address OpenApi too, that brakes it.
For me a no-no.

tkurki

Cool, this eliminates nicely the "double sidebar" problem but still allows navigation back to the main app via hamburger menu, SK logo and back button.

Url stays in sync and back button works 👏

The home button did not work for me, double SK logo is still there?

tkurki · 2026-01-25T07:52:58Z

I don't agree with the user getting "trapped" with this. But collapsing the sidebar, that otherwise is not something I ever tuse, could be even a better option to save & eat the case.

@bkeepers thoughts?

The switch / contrast with the main Admin UI and docs is still pretty jarring, but than can be addressed separately by adjusting the docs styling.

tonybentley · 2026-01-25T08:21:46Z

Cool, this eliminates nicely the "double sidebar" problem but still allows navigation back to the main app via hamburger menu, SK logo and back button.

Url stays in sync and back button works 👏

The home button did not work for me, double SK logo is still there?

When you load the docs independent of the admin the logo becomes full sk instead of home icon. I think the home is just icon and not linked. I can change behavior though. Also we can include white style in this pr or I can work on it for the next pr. Will change based on if in iframe to white, otherwise keep it the same dark mode. ...or change based on consensus

tkurki · 2026-01-25T08:36:41Z

This is what I see - no Home icon.

In current release the SK logo at top left of the docs takes you to docs start page with Introduction. Are you saying that the home icon would not do the same? Why would we have it there if it is not clickable?

More like your decision to continue with styles in this PR or another. If it's going to be later then another, if continue right away to that then this PR, just more commits.

tonybentley · 2026-01-25T08:58:16Z

This is what I see - no Home icon.
In current release the SK logo at top left of the docs takes you to docs start page with Introduction. Are you saying that the home icon would not do the same? Why would we have it there if it is not clickable?
More like your decision to continue with styles in this PR or another. If it's going to be later then another, if continue right away to that then this PR, just more commits.

Just curious if you rebuilt docs after pulling my changes? Maybe clear cache? Then verify the embedded class is being added by checking DevTools on the iframe's element. It should work

tkurki · 2026-01-25T10:16:26Z

Ah my mistake, just rebuilt the admin ui 🤦 . Forget that…

bkeepers

I'm still not sure I understand the goal of moving the docs into an iframe. Especially in this iteration where almost everything is hidden.

Can you help me understand?

Is there any way those goals can be achieved by just improving the typedoc theme?

bkeepers · 2026-01-25T10:50:01Z

packages/server-admin-ui/src/views/Webapps/EmbeddedDocs.js

+            '/documentation',
+            ''
+          ) || '/'
+        history.replace('/documentation' + currentSubPath + newHash)


I haven't pulled this down and tested it compard to the gist I shared the other day, but there are a lot of issues with this hashchange approach. Sometimes the back/forward button doesn't work. Sometimes it gets out of sync (especially on embedded pages that include ahash, like the is common in documentation).

tkurki · 2026-01-25T11:42:14Z

keep docs within admin ui instead of opening a separate window or tab
make/keep docs deep linkable
support navigation within the docs by Table Of Contens as well as navigation to other parts of the admin ui while minimizing the number of navigation on top of navigation levels

bkeepers · 2026-01-25T12:03:04Z

@turki I still don't understand how an iframe is the solution to those issues.

keep docs within admin ui instead of opening a separate window or tab

The docs are always served from a server instance, so adding a "Home" icon to take the user back to / would solve this?

make/keep docs deep linkable

They already were deep linkable in their current form. e.g. https://demo.signalk.org/documentation/Developing/REST_APIs/History_API.html#query-parameters

support navigation within the docs by Table Of Contens as well as navigation to other parts of the admin ui while minimizing the number of navigation on top of navigation levels

The docs will be side-by-side with other parts of the UI? What I see in this PR is that they take up the entire screeen like before, but now they have a Home button and are in an iframe.

Sorry if I'm misunderstanding something. Maybe I need a cup of coffee. I just never saw rational in #2248 for this change and am still confused what problems were tyring to be solved by moving it into an iframe that couldn't be solved by updating the TypeDoc theme.

tkurki · 2026-01-26T13:47:15Z

keep docs within admin ui instead of opening a separate window or tab

The docs are always served from a server instance, so adding a "Home" icon to take the user back to / would solve this?

"Keep docs within admin ui, under the familiar header and admin ui navigation readily accessible"

make/keep docs deep linkable

They already were deep linkable in their current form. e.g. https://demo.signalk.org/documentation/Developing/REST_APIs/History_API.html#query-parameters

Sure, if you know that you can do that. "Make docs deep linkable by just navigating to a doc page and simply copypasting the url "

support navigation within the docs by Table Of Contens as well as navigation to other parts of the admin ui while minimizing the number of navigation on top of navigation levels

The docs will be side-by-side with other parts of the UI? What I see in this PR is that they take up the entire screeen like before, but now they have a Home button and are in an iframe.

They are embedded within the Admin UI, creating a much less yanky "i took you someplace else to see the documenation" experience.

Here's a picture of what I see as a reasonable short term goal:

This differs from the PR:

admin ui sidebar is minimized, not hidden - same as pressing the < button in the sidebar footer
there is no "home" button in the docs - less clutter

For some reason the docs icon in sidebar is blue?

In my testing I did not see any problems with the url being out of sync with where I was.

KEGustafsson · 2026-01-26T16:31:52Z

I'm not really fan of this embedding.

With this PR you are either on documents or server, both are not possible like old tab approach. Of cource you can open document in a new tab, but then it opens second instance of SK too.

How complicated it is that you have multiple tabs open in web browser?

Jumping between specific doc and server pages becomes more difficult. This is not making things easier. Might look nice but usability is poor.

Tony Bentley and others added 2 commits January 23, 2026 21:49

feat(typedoc-theme): show home icon instead of logo when embedded

c3a0e5f

Detect iframe context via inline script, toggle CSS classes to show Signal K logo in standalone mode and a home icon when embedded in the Admin UI. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

tkurki added the fix label Jan 25, 2026

tkurki reviewed Jan 25, 2026

View reviewed changes

bkeepers reviewed Jan 25, 2026

View reviewed changes

Uh oh!

feat: documentation page deep linking and UI cleanup #2289

Are you sure you want to change the base?

feat: documentation page deep linking and UI cleanup #2289

Conversation

tonybentley commented Jan 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Standalone — Signal K logo

Embedded in Admin UI — home icon

Test plan

Uh oh!

dirkwa commented Jan 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tonybentley commented Jan 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dirkwa commented Jan 24, 2026

Uh oh!

dirkwa commented Jan 24, 2026

Uh oh!

dirkwa commented Jan 24, 2026

Uh oh!

tonybentley commented Jan 24, 2026

Uh oh!

dirkwa commented Jan 24, 2026

Uh oh!

tkurki left a comment

Choose a reason for hiding this comment

Uh oh!

tkurki commented Jan 25, 2026

Uh oh!

tonybentley commented Jan 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tkurki commented Jan 25, 2026

Uh oh!

tonybentley commented Jan 25, 2026

Uh oh!

tkurki commented Jan 25, 2026

Uh oh!

bkeepers left a comment

Choose a reason for hiding this comment

Uh oh!

bkeepers Jan 25, 2026

Choose a reason for hiding this comment

Uh oh!

tkurki commented Jan 25, 2026

Uh oh!

bkeepers commented Jan 25, 2026

Uh oh!

tkurki commented Jan 26, 2026

Uh oh!

KEGustafsson commented Jan 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

tonybentley commented Jan 24, 2026 •

edited

Loading

dirkwa commented Jan 24, 2026 •

edited

Loading

tonybentley commented Jan 24, 2026 •

edited

Loading

tonybentley commented Jan 25, 2026 •

edited

Loading