Support direct links to options on Configuration documentation site

[calebcartwright]

AFAIK our Configuration documentation site doesn't support direct links to configuration options. It'd be great to be able to do so like we can with the in-repo markdown file.

Works 👉 https://github.com/rust-lang/rustfmt/blob/master/Configurations.md#reorder_modules
Doesn't work 👉 https://rust-lang.github.io/rustfmt/#reorder_modules

I suspect the solution for this will end up being closely related to #4260, though opening as a separate issue in case it can be solved more quickly/independently.

Also refs #4178 and #4221

[aszenz]

@calebcartwright

After reading about this issue and wanting to work on it I find that by clicking on the link https://rust-lang.github.io/rustfmt/#reorder_modules the configuration options are being filtered by the hash text.

So the link essentially fills in the search bar with reorder_modules and then the options are filtered by this text, thereby showing just the reorder_modules option.

So in a way this is already supported but instead of a direct link the hash term is used for search.

[hbina]

@aszenz Was looking into this as well. That is really wonky, it does not even filter out the first 2 sections...

[aszenz]

@hbina That seems deliberate the first two sections are headers and the search only applies to the configuration options, the searchTerm is filled in from the url hash as well

[calebcartwright]

Yup, the current search is more of a filter/show all options that include the needle text within their section. This is particularly noticeable for common items (try using max_width for example)

[aszenz]

Yes and is it something that should be changed, I do see it as being less useful than direct linking.

[calebcartwright]

I do see it as being less useful than direct linking.

I see these as orthogonal, and don't want to minimize either. It's entirely valid that a user may want to narrow down the page content to a specific area they are interested in at that moment (for example "show me all the options that impact match formatting)

[aszenz]

I see these as orthogonal, and don't want to minimize either. It's entirely valid that a user may want to narrow down the page content to a specific area they are interested in at that moment (for example "show me all the options that impact match formatting)

Yes that's what search is for, but using the url hash for search is a bit unorthodox, usually its done using a query parameter like ?search=term. The hash is usually reserved for directly linking to specific parts of the page.

[calebcartwright]

@aszenz - My point is that both search/filter and direct linking/navigation are equally useful and that we need to support both.

I'm entirely open to any solution that delivers both, including any that changes the current uri search behavior. We just can't go with an approach that provides direct linking/navigation but removes search/filter entirely.

[ayazhafiz]

I agree with @calebcartwright, both should be supported. The search term is better as a query param, and linking to the header of an option with a url hash is easy, the markdown renderer just needs to be given a function to render the header with an id equal to the option name. Adding a link icon like github does can be done the same way.