Please add OpenSearch search function offer

[Enyium]

Suggestion

OpenSearch description format: https://developer.mozilla.org/en-US/docs/Web/OpenSearch

By adding an XML file to your HTML and server, people will be offered to add a search function in their browsers that searches with a URL like https://microsoft.github.io/windows-docs-rs/doc/windows/?search={searchTerms}. Then you wouldn't need a bookmark, which is more cumbersome to utilize.

[riverar]

Great idea. Those pages are automatically generated via rustdoc so I think we'd need to keep manually patching the output to reference OpenSearch XML. I'll take a closer look though.

I recommend creating an issue at https://github.com/rust-lang/rust/issues/ about getting this added to rustdoc itself. Closing this issue for now as there's nothing to do here (for the crate itself). Feel free to keep the discussion going though!

[Enyium]

rustdoc has --html-in-header! That wouldn't be hacky patching.

I don't think rustdoc would be changed to always include the OpenSearch stuff. And if it would be a more semantic, dedicated OpenSearch-related switch, it wouldn't make much of a difference towards the --html-in-header solution.

[Enyium]

@riverar: Would you please consider reopening the issue, since you made the incorrect assumption that rustdoc would need to change something to support this, while it already does support it?

[riverar]

Sure, thanks for the ping.

[kennykerr]

I'm not convinced this has anything to do with windows-rs and that Windows crates should support this if it's not applicable to Rust crates generally. There should at least be a discussion with the rustdoc folks about this at the very least before anything happens in the windows-rs project.

[riverar]

@Enyium I added this to the latest deployment of https://microsoft.github.io/windows-docs-rs/doc/windows/ but not sure how to test it. Also suspect this will never work with the sub-domain/folder hierarchy we have.

[Enyium]

@riverar:

It works well! I now have the search function "Rust for Windows".

The only strange things are these:

• Before adding the search function, it had a black Rust symbol as the offer. After adding, waiting and switching some browser tabs, the added search function now has a four-colored Windows symbol. Maybe the Rust symbol is because the of the page's favicon for some reason (you used the microsoft.com favicon in the .xml, which explains the Windows logo).
• After adding, it's still offered to me for adding it again. When I try that, I get the message (translated to English): 'Firefox Developer Edition could not download the search engine from "https://microsoft.github.io/windows-docs-rs/opensearch.xml" because a search engine with the same name already exists.'

There's a problem with your .xml file that could perhaps be the cause of some problems. Here, it says about the title attribute of the <link> element: "must match your plugin file's <ShortName>". But you used different strings.

Maybe for the icon you could use the four-colored Windows logo without white bars and use the Rust logo as a mask to give the colors the Rust logo shape. Then maybe add a thin black border around the shape. Or, if you can't be bothered with this complexity, add the Windows logo to the Rust logo like a small shortcut overlay is added to .lnk file icons under Windows.

---

@kennykerr:

Why should you have to talk to the rustdoc folks when they offer CLI switches to change the HTML according to your demands yourself?

I don't view the windows-Crate as just another crate, since it may be used across projects, not simply something you need for a certain project, and requires considerably more looking up of things. But, granted, you could argue that there are also other very basic crates like tokio, and you might like a search function for that, if you're repeatedly needing to search it. But, in my understanding, the people to contact for that would not be the rustdoc folks, but the docs.rs folks that have automated pipelines using rustdoc. However, what's an icon-identified search function without a distinguishing icon? And crates don't come with icons.

[riverar]

@Enyium Good catch on the xml, will fix that. Can you provide some test steps so I can test locally? I tried using the URL in Chrome, Edge, and Firefox and nothing happened--perhaps I have something locked down?

[Enyium]

This is what I found out:

• Chrome and derivates don't support auto-discovery of site-specific search engines anymore: https://stackoverflow.com/a/75765618. They say: "new Site search shortcuts are no longer automatically added to the Chrome search bar." But I couldn't find any way to add it using the information in the OpenSearch XML file of a site. As far as I know, you can only add it manually via chrome://settings/searchEngines.
• In Firefox, you can't add a search function manually, but only via the OpenSearch XML file that the browser presents as an offer. Search engine add-ons were removed from addons.mozilla.org (2019), but in the comments, it was answered: "Firefox isn’t losing its ability to surface OpenSearch plugins listed in tags."

In Firefox Developer Edition, I have my layout arranged so that I have a dedicated search textbox to the right of the address bar. There, I can easily acccept the offer. But when clicking on the address bar text, this is also possible with the flyout box that appears (via the icon bar at the bottom).

If you want to check another functioning OpenSearch engine, github.com has one.