No search in Rails Guides

A May Of WTFs
1

It blows my mind that Rails Guides don’t have search built in. Sure I can use site:guides.rubyonrails.org in Google, DuckDuckGo, etc., but that’s a pain. And let’s face it, it’s a bit weird considering the guides are the friendly face of an infinitely flexible web app framework!

20 Likes
2

Thanks for pointing this out!

1 Like
3

While I’m here, the number of “Work in progress” sections in the guides can be a little off-putting. Not so much WTF, but more HTF give the maturity and stability of Rails. Remember, this status means the sections don’t show in the Guides Index either.

Is there any advantage of marking sections as in progress, given that all of the sections are constantly being updated?

2 Likes
4

That mark is being used internally for guides that were never published neither reviewed by the documentation team. Those guides are incomplete or wrong, so a point could be made to not even show them in the website.

5

I can see why for example the ActionText documentation is “Work In Progress” but I’m not sure why “Action View Overview” is still WIP. I’d like to help making it non-WIP.

1 Like
6

It does seem silly I only go to rails guides for overviews and the occasional google result - but for every day I use Ruby on Rails - APIdock .

1 Like
7

API Dock is not Rails official API documentation. The official docs are at https://api.rubyonrails.org/. Docs for the next version at https://edgeapi.rubyonrails.org/.

6 Likes
8

Right - that is exactly my point. Because it is well indexed and searchable, I rely on API Dock instead of the rails guides or API docs. In my ideal magical world, I would go to the official pages and they would all be well indexed, well integrated, and very searchable.

And, ideally, commentable like API dock is - because that is also super useful.

4 Likes
9

I love the commentable feature. It feels like PHP documentation in the old days. You’ll learn a lot just from the comments

1 Like
10

+100 could we please add a search and bring the useful stuff from APIdock, is painfully slow to search anything, but is the only good place we have now (unless we improve the oficial)

1 Like
11

I would be happy to help set up DocSearch in rails guides!

DocSearch: Search made for documentation

4 Likes
12

Thanks @Spone. That was already proposed in the past, but we did not follow this route. The conversation is long, but there’s a summary here.

5 Likes
13

Thanks for not including algolia search. There is a trully open source alternative called Lunr.js

https://lunrjs.com/

Should we consider that?

2 Likes
14

@skatkov awesome, thank you. IIRC there has been some proposal with search in pure JavaScript (the websites are static). Maybe even a patch, @rafaelfranca probably remembers it.

1 Like
15

Thanks @fxn I was not aware of this discussion.

Another alternative would be to use an Elasticsearch instance and index the guides contents as part of the build process, then run searches from the frontend against Elasticsearch, but I’m not experienced in this approach.

16

I actually liked this Proof of Concept: https://github.com/rails/rails/issues/36218#issuecomment-496680549

Maybe it’s easier to build a simple search with javascript only, like outlined in the mentioned issue comment?

I’d love to help finalize this feature

1 Like
17

Aaahh yes! That was the one. Yes, I think that would be nice to investigate. We should revive that proof of concept and see where do we get.

18

I might be mistaken, but Lunr.js seemd JS based without any back-end components and should work with a static website.

19

I took a look at it last night and all of the Guides’ markdown is just 2MB, uncompressed. With GZIP + a simple search in JS, you could provide this easily without the need to set up a backend.

6 Likes
20

Luckily, the guides are not a SPA and we have some spare MBs to download :joy:.

7 Likes