diff --git a/src/doc/rustdoc/src/SUMMARY.md b/src/doc/rustdoc/src/SUMMARY.md index ae94527e2b4..3fa91bb51f0 100644 --- a/src/doc/rustdoc/src/SUMMARY.md +++ b/src/doc/rustdoc/src/SUMMARY.md @@ -10,5 +10,6 @@ - [Lints](lints.md) - [Advanced features](advanced-features.md) - [Unstable features](unstable-features.md) +- [Website features](website-features.md) - [Passes](passes.md) - [References](references.md) diff --git a/src/doc/rustdoc/src/website-features.md b/src/doc/rustdoc/src/website-features.md new file mode 100644 index 00000000000..5fade4e84a9 --- /dev/null +++ b/src/doc/rustdoc/src/website-features.md @@ -0,0 +1,25 @@ +# Website features + +These features are about using the website generated by `rustdoc`. + +## Custom search engines + +If you find yourself often referencing online Rust docs you might enjoy using a custom search +engine. This allows you to use the navigation bar directly to search a `rustdoc` website. +Most browsers support this feature by letting you define a URL template containing `%s` +which will be substituted for the search term. As an example, for the standard library you could use +this template: + +```text +https://doc.rust-lang.org/stable/std/?search=%s +``` + +Note that this will take you to a results page listing all matches. If you want to navigate to the first +result right away (which is often the best match) use the following instead: + +```text +https://doc.rust-lang.org/stable/std/?search=%s&go_to_first=true +``` + +This URL adds the `go_to_first=true` query parameter which can be appended to any `rustdoc` search URL +to automatically go to the first result. diff --git a/src/librustdoc/html/static/search.js b/src/librustdoc/html/static/search.js index 67be7b99155..0aebb0e9d65 100644 --- a/src/librustdoc/html/static/search.js +++ b/src/librustdoc/html/static/search.js @@ -1058,14 +1058,14 @@ window.initSearch = function(rawSearchIndex) { return ""; } - function showResults(results) { + function showResults(results, go_to_first) { var search = searchState.outputElement(); - if (results.others.length === 1 + if (go_to_first || (results.others.length === 1 && getSettingValue("go-to-only-result") === "true" // By default, the search DOM element is "empty" (meaning it has no children not // text content). Once a search has been run, it won't be empty, even if you press // ESC or empty the search input (which also "cancels" the search). - && (!search.firstChild || search.firstChild.innerText !== searchState.loadingText)) + && (!search.firstChild || search.firstChild.innerText !== searchState.loadingText))) { var elem = document.createElement("a"); elem.href = results.others[0].href; @@ -1242,7 +1242,7 @@ window.initSearch = function(rawSearchIndex) { } var filterCrates = getFilterCrates(); - showResults(execSearch(query, index, filterCrates)); + showResults(execSearch(query, index, filterCrates), params.go_to_first); } function buildIndex(rawSearchIndex) {