New HexDocs home page

[josevalim]

Today's home page is fully done in the client, we should probably mirror that here.

Overall, the main feature we want to have is full-text search across (at least) one or more packages. You can add packages by typing # which will trigger an autocomplete, such as #phoenix_live_view. You can then press : to autocomplete a given version, otherwise the latest is picked from the hex.pm API. If the search only has the package information, such as #ecto or #ecto:1.0.0, and no search term, we go to the particular package (+ version).

Anything else we could do when it comes to search? /cc @ericmj @ruslandoga @wojtekmach

I will work on a mockup to the new homepage. The mix hex.search and ExDoc can come later.

[josevalim]

Once we submit the search, we should go to a page like this: https://claude.site/artifacts/3324d578-85b1-411c-accd-c002f37f301b

I am currently in touch with Livebook's designer so he can mockup the new home page plus search. @paulo-valim made himself available to implement the designs as HTML + Tailwind. We already have endpoints in Hex for:

1. Package autocompletion
2. Docs search (coming with Expose the typesense server via search.hexdocs.pm #47)
3. And another for creating short URLs

We will just need someone to implement the front-end bits. I will post all future updates here.

[josevalim]

@ruslandoga I am wondering: should we also index the most recent versions of packages as phoenix-latest, so it is easy for us to always query the latest? In the same way that hexdocs already tracks that hexdocs.pm/phoenix means latest?

[josevalim]

Another potential feature we want to borrow from ExDoc is using title:, doc: and type: to scope search. Here are all features available in ExDoc search:

• Multiple words (such as foo bar) are searched as OR
• Use * anywhere (such as fo*) as wildcard
• Use + before a word (such as +foo) to make its presence required
• Use - before a word (such as -foo) to make its absence required
• Use : to search on a particular field (such as field:word). The available fields are title, doc and type
• Use WORD^NUMBER (such as foo^2) to boost the given word
• Use WORD~NUMBER (such as foo~2) to do a search with edit distance on word

[josevalim]

@ruslandoga @ericmj @wojtekmach @supersimple I just want to share with you the new designs for the home page:

And the package search functionality:

We will work on converting those to HTML, then I will let you know once that's ready :)

[supersimple]

Looks good. I know at least one person that will be happy ;)

[lpil]

Hello everyone! @ghivert may be able to help out here with the frontend with Gleam+Lustre.

P.S. Love the design there, the homepage especially looks really nice.

[ghivert]

Hi everyone! @lpil told me about a potential rewrite with Lustre in Gleam.
I’d be happy to help on the subject and implement the frontend part!

If I understand everything correctly, the backend part is already written, so the main task is only to implement the mockup as a real web app? Is there some requirements like SSR, or anything else?

In case you have a Figma/Sketch/whatever format for the mockups, maybe it could directly translate into a Lustre + Tailwind?

[josevalim]

Oh! Being to able to keep it within the BEAM community would be fantastic, thanks for chiming in @lpil and @ghivert!

If I understand everything correctly, the backend part is already written, so the main task is only to implement the mockup as a real web app? Is there some requirements like SSR, or anything else?

Yes, the backend is existing Hex APIs and the newly added Search API. Our goal is also to serve a static page, so no SSR. We probably want the homepage (the first screen) to be indexable though but I guess that should be doable. And I was told most engines index using a JS engine anyway?

In case you have a Figma/Sketch/whatever format for the mockups, maybe it could directly translate into a Lustre + Tailwind?

We do have one. We also have someone who can do the translation from Figma mockup to HTML + Tailwind. Or would you rather tackle it too?

This is very exciting!

[ghivert]

I'm really happy to be able to help!

Yes, the backend is existing Hex APIs and the newly added Search API. Our goal is also to serve a static page, so no SSR. We probably want the homepage (the first screen) to be indexable though but I guess that should be doable. And I was told most engines index using a JS engine anyway?

What we could do is performing some SSG in that case: no full-fledges SSR, but the HTML statically served contains the initial render. So it could be nicely indexed by search engines, and client-side runtimes will then take care of rendering the content after that (with hydration). I think it makes sense at least for the homepage to be pre-rendered, to improve search engine indexing.
Also, Google is now indexing web sites with a JS engine enabled. I'm not sure Bing is doing it too however.

I think the SSR question is also related to the support of the Open Graph Protocol for Hex. Without SSR, it's not possible to have proper Open Graph tags. With OG tags, we could provide nice displays on some applications, like Discord or Slack when linking HexDocs URL. I'm not sure it's really useful, and it will be more work.

I think it's possible to start with a first implementation entirely client-side, and potentially migrate server-side later if needed (if things like OG tags are required).

We do have one. We also have someone who can do the translation from Figma mockup to HTML + Tailwind. Or would you rather tackle it too?

To be fully transparent on that point, Tailwind is not my favorite tech. If you have someone who's expert with (or at least used to), I think it can be a way to gain some time, but they're too much busy, I can tackle it too. 🙂

Talking about time, do you have some deadline for a working implementation?

[josevalim]

To be fully transparent on that point, Tailwind is not my favorite tech. If you have someone who's expert with (or at least used to), I think it can be a way to gain some time, but they're too much busy, I can tackle it too. 🙂

We are open to alternatives, if you have any mind. :) I suggested Tailwind because it is most likely others will be familiar with it. @paulo-valim made himself available to translate to Tailwind but that will probably only happen within a month. We don't have a deadline per se, given it is all open source.

[josevalim]

Correction, @paulo-valim has already started working on HTML + Tailwind, so we should have something as base sooner than later. :)

[ghivert]

I'm on the pure CSS side of the force! I consider CSS simpler than any framework, but as any take, it's highly debatable 😉

If @paulo-valim started working on it, I'd suggest to wait for him to finish, and then implement the HTML in the Lustre code. That will be less work UI-related and more time to properly implement the flows!

Thanks for your answers about the deadlines.
I can start taking a look this week-end. And experimenting with the search API if it's available?

[josevalim]

I can start taking a look this week-end. And experimenting with the search API if it's available?

Perfect. We will work on getting the API descriptions for you before the weekend (hopefully tomorrow!).

[ghivert]

I can start taking a look this week-end. And experimenting with the search API if it's available?

Perfect. We will work on getting the API descriptions for you before the weekend (hopefully tomorrow!).

Thanks ! No worry though, if you need some time, I can still postpone experimentation (I thought API descriptions were already written). Do not crush for me! 🙂