Enhance search experience for Aliki

[ccmywish]

Recently, I have been extensively using the current https://docs.ruby-lang.org/en/master/, I like aliki so much, but I find I want it more convenient to use. So I add/adjust these features:

1. Use Escape to leave search region
2. Use / to search globally
3. Use s to search instance methods in the current module page
4. Use Shift + s to search class methods in the current module page
5. Autocomplete single : to ::

[ccmywish]

@st0012

This is not a big change. Could you please take a look and review it?

[matzbot]

🚀 Preview deployment available at: https://0ccba8f5.rdoc-6cd.pages.dev (commit: db02096)

[ccmywish]

The preview page does't work with s and Shift + s because the page lacks .html suffix (Maybe cloudflare page service hides it?), so the match failed:

UPDATE: I submitted an additional commit to make it compatible with this.

[st0012]

Thanks for the ideas and PR 😄

I like idea 1, 2, and 5 but am not sure about 3 and 4.

On GH, s and / are both shortcuts for searching. If we introduced 3, s will match GH's behaviour on non-class/module pages. Combining with /, this will likely give users the impression that we're matching GH's shortcuts intentionally.

But once they moved to a class/module page, s suddenly isn't a simple search shortcut anymore. For searching other classes/modules, it'd be easier to use / instead. However, at the point you realised this after hitting s, you can't simply hit / to switch the search mode anymore. You'd have to manually delete all the pre-filled input, which is annoying.

So this is my first concern: the rather complex behaviour will make the feature harder to learn and also harder for future maintenance.

My second concern is that we still don't have a good way to showcase available shortcuts to users. I'd like to avoid adding new shortcuts before we solved this problem. Or we risk adding features that'll be in general under-utilised.

Autocomplete single : to ::

I think this should be applied to mobile too.

[ccmywish]

@st0012 Thank you for your feedback and suggestions. 👍

However, at the point you realised this after hitting s, you can't simply hit / to switch the search mode anymore. You'd have to manually delete all the pre-filled input, which is annoying

Not really. Escape can make you quit input area, and then hit / will delete all input.

2026-02-02.134722.mp4

the rather complex behaviour will make the feature harder to learn and also harder for future maintenance.

As you can see in the video, this action is not complicated. Just press Escape. Moreover, in the placeholder, it has already indicated that (shift) s is applicable to the current class/module, so people should have a basic expectation.

As for maintenance, the main complexity lies in the fact that the desktop and mobile versions have slightly different search interfaces, which may result in some code duplication. However, this is the complexity brought about by the architectural choice.

Considering that the main scenario for people to program is still on the desktop, we can temporarily only add this search shortcut for the desktop version.

My second concern is that we still don't have a good way to showcase available shortcuts to users. I'd like to avoid adding new shortcuts before we solved this problem. Or we risk adding features that'll be in general under-utilised.

I think search within the class/module is quite important. In contrast, repeatedly typing out prefix class/module name is annoying. I noticed that you have a high level of concern for the user experience, so you will surely be able to quickly grasp this point.

Autocomplete : applied to mobile too.

I've made a new commit. Now it works both on mobile and desktop.

[st0012]

As you can see in the video

If I need a video to understand how to proceed in that situation, IMO that's too complicated 🙂

I think search within the class/module is quite important. In contrast, repeatedly typing out prefix class/module name is annoying.

I don't deny the helpfulness of such features. My concern is on how we can better design it so users can discover them easier. Let me give you one example: RDoc's previous default theme, darkfish, has had several shortcuts (including /) for many years. And I only discovered them when I modify the code as a maintainer. Most of the Ruby devs I know also never knew about them. This is what I want to avoid.

And I honestly don't think putting a complicated instructions as placeholder is the solution.

What does inside the class mean if I'm not inside a class? Does that apply when I'm in a module's page? What does shift do if it's optional?

One better solution will be to have a help modal for the features we support, like what Rust does:

I noticed that you have a high level of concern for the user experience, so you will surely be able to quickly grasp this point.

I don't appreciate this rhetorical framing. It implies that if I don't accept the feature as proposed, I lack concern for UX.

[ccmywish]

If I need a video to understand how to proceed in that situation, IMO that's too complicated

Since the preview for this PR is no longer available, I'm providing the video to make it easier for all those who can view this PR to review it again, without the need for them to rebuild it themselves.

My concern is on how we can better design it so users can discover them easier

Now I get it, the current placeholders are indeed not sufficient.

I don't appreciate this rhetorical framing. It implies that if I don't accept the feature as proposed, I lack concern for UX.

❤️ Don't be so nervous. You don't have to infer the opposite meaning from this sentence. On the contrary, I really like Aliki. Before this, I never used the official documents. So I fully respect your opinion. You can keep this PR in any state you like. Thank you for your work.

[st0012]

I don't plan to stale the PR, just can't accept it as a whole as it is. If you're ok with it, you can submit improvements 1 and 2 in a separate PR and it'll be easier for us to merge it.
And then we can focus this PR on adding additional enhancements.
But I also think we should probably create the shortcut help modal first as the foundation for more advanced shortcuts.