Customize Search Results

[zachdaniel]

Recently, I built ash-hq.org as a way to solve for some discoverability issues with the many packages provided by Ash. However, #1551 goes a long way to help with that problem, allowing at least name-only search across packages. However, AshHq also has the ability to search for DSL items as first class items, instead of their associated function/modules which gets very noisy because the DSLs are nested and so search would show things like Ash.Resource.Dsl.Attributes.Attribute.attribute and its just not very intuitive. So I have two ideas to help with this:

1. support something like autocomplete.json which is a JSON file of additional search items and where they should link to. This could be generated by Ash when building docs.

2. perhaps Ash DSL documentation could be automatically built as a cheat sheet, and we could then support autocompleting cheat sheet items in the search bar

[josevalim]

Hi @zachdaniel! Regarding custom entries, how would they be specified and where would they link to?

Something else we should do is add subheaders (h2) from pages/guides to the search. This way, if you have an "attribute" section, it would should up (so you could have a DSL guide). WDYT?

[zachdaniel]

TBH its up in the air a bit, as I'm just considering how I can bring ash_hq back into the hexdocs fold (I might not even decide to do that, but if I can get a good experience for users, I hope to). I don't think just h2 would be enough because Ash DSLs are deeply nested. This is what it looks like in AshHQ, for example:

So what I'm looking for is a way to 1. display the documentation for a large nested DSL nicely, and 2. include all of the associated option names in search in some way. In AshHq, for instance, we show the full path to the DSL and a preview of its docs:

So if I can construct a similar thing, in like a JSON file or in an option in the docs() configuration in mix.exs (that I would need to read from a JSON file 😆 ), then I could potentially have a viable alternative for search. I would also probably add DSLs that are provided by other Ash libraries to that JSON file, and have them link to said package.

This comment is about more than just this issue at this point, but another thing AshHq does is allows you to select which version of a given package you are using, and will replace links to said package accordingly, and provide docs as of each individual version. I think its very useful, but I'm willing to sacrifice that for a unified hex + ash docs experience, and instead just have the docs be based on the latest versions of packages whenever the Ash core docs were last published.

[josevalim]

I see. We could have a autocomplete_references: %{"Foo" => "https://"} in your project configuration. Using pretty much the same structure we settle on from #1551.

[zachdaniel]

I think what I'm basically considering is something similar to cheat sheets, where Ash provides a mix task that will produce special markdown or html files for any DSL modules, and then can also produce a set of custom search results that will link to the appropriate anchors in the DSL section.

[zachdaniel]

Yeah, agreed. The rest I can do myself as part of Ash building its docs. Although another trouble I'll have is that as the Ash ecosystem grows, there are things that people don't use, that if I do it this way they'll have to wade through the search results. Lots for me to consider here, so perhaps the only real way to get what I want is to do a more heavy handed thing where ex_doc produces all the docs but I build a custom sidebar and search bar.

[josevalim]

Closing this for now. I will be glad to resume this discussion once the first step on #1551 is given. PRs welcome!