Redoing the landing page so it looks less like a FAQ

[lubianat]

tl;dr:

Redoes the landing page and moves the questions to the FAQ.
Safe to ignore the comments/thread.

ping for thoughts perhaps @jo-mueller @govekk @will-moore?

To review:
– Look at the rendered page, see if it works

• Notice the at the changed files the extra lines in custom.css and main.js; at least don't see any red flags

Text updated: Aug 11, 2026

[github-actions]

Automated Review URLs

• Readthedocs

[jo-mueller]

Uh, love the cards. Can the cards also be arranged horizontally/in a gridded layout? Like, for instance over at scikit-learn or ro-crate? We could then add images into each card to make the landing page a bit more vibrant?

[lubianat]

Uh, love the cards. Can the cards also be arranged horizontally/in a gridded layout? Like, for instance over at scikit-learn or ro-crate? We could then add images into each card to make the landing page a bit more vibrant?

nice suggestion! something like:

(suggestions for images for each card welcome)

Maybe I drop the big image on the top, it is noisy too

[jo-mueller]

Cool! Maybe some emoijs for the grid card headers?

i.e.,

• Community : 💬
• Specifications: 📜
• RFC: ❗
• resources 📚
• Publications: 📢
• Help desk ☎️

Maybe we also find a suitable image for each card?

[lubianat]

@jo-mueller what about something like:

[jo-mueller]

Love it.

Nitpick: I would choose bottom-anchoring for the text in the cards to make it look slightly tidier.

[lubianat]

Sure, good one. I may also slightly edit the images so they are more consistently sized.

Good thing is that in mobile they fall very naturally.

Maybe a next stepcis adding cards to the other pages so navigation is more natural for mobile (and people with big thumbs)

(I am on mobile, I ran the GH copilot agent with instructions to come up with a simple alignment there, let's see what it can do)

[lubianat]

Also, link to the #RFCs was broken

We need to merge

• Adds HTML-Proofer and fixes broken links #567

To catch these things quicker. @jo-mueller, could you review there too?

[jo-mueller]

Love it. Just for my understanding (I'm not super-familiar with css stuff):

The :::{div} ome-hero tells the page to use the custom.css defined elsewhere, which takes care of stuff like alignment grid entries?

[lubianat]

The :::{div} ome-hero tells the page to use the custom.css defined elsewhere, which takes care of stuff like alignment grid entries?

The custom.css is in the folder for static files, which also serves a "main.js" used elsewhere.
The :::{div} ome-hero adds an "ome-hero" class to this div, which allows the custom.css to control it.

"Hero" is web dev jargon for the prominent image/header of a website. The new custom.css says things like:

.ome-hero {
  text-align: center;
  margin: 0 auto 3rem;
}

i.e. put it in the center and give it some margin

The aligment of grid entries is done via the sphinx-design card spec, e.g.

::::{grid} 1 2 2 3
:gutter: 3

The custom.css also does some tricks to make the images x text look nicer/aligned inside each card

[joshmoore]

Updated the description with this lovely screenshot :)

[jo-mueller]

Supercool, I'm all for it. It's a bit strange that github allows me to merge this PR though? 🤔

[lubianat]

Supercool, I'm all for it. It's a bit strange that github allows me to merge this PR though? 🤔

I think it is opened against the "link-fixes" branch, because I wanted the html-proofer checks. But that did not work.

Only the main branch is protected

The base branch was changed.

[lubianat]

A bug before moving forward:

When hovering the cards with the mouse, it "pre fetches" the content of the page (so it is in theory loaded when clicking the button).

Some of the links are heavier due to iframe (community) and the JS calls on "Publications" to EuropePMC.

This ends up messing up with the navigation on the landing page. The buttons ended up in seemingly random locks (as they wait for the result of the pre-fetch). Or at least that is my interpretation of the bug

Edit: bug fixed

[jo-mueller]

This ends up messing up with the navigation on the landing page. The buttons ended up in seemingly random locks (as they wait for the result of the pre-fetch). Or at least that is my interpretation of the bug

So...python code to generate a .bib file for the references after all? 🤓

[jo-mueller]

Somehow the hover-over doesn't work for the cards except for the community and resources cards:

07.08.2026_13.37.22_REC.mp4

[lubianat]

@jo-mueller yes, I am figuring out.

The big pain for me is that it works when I build it locally with sphinx, so there is something specific for the RTD build that is messing with the cards...

Gravacao.de.tela.de.2026-08-07.08-45-39.mp4

[lubianat]

Lot's of unwanted learning!

• 1 RTD injects things on our pages.
  The advertisement is the clearest, but opening the browser DevTools we see things like:

<readthedocs-linkpreviews></readthedocs-linkpreviews>
<script async="" type="text/javascript" src="/_/static/javascript/readthedocs-addons.js"></script>

• 2 Some addon (perhaps linkpreviews) triggers pre rendering

That means that when users hover one link, the content of the link is prefetched (meaning, html+artifacts are sent) and prerendered (meaning, iframes are loaded, js runs and the like).

Which means pages that are costly (such as "Community" which has an iframe, or the script in "Publications") are actually fetched not only when the link is clicked but als when it is hovered. This has performance implicatinos.

https://docs.readthedocs.com/platform/stable/link-previews.html

This blocks the thread and makes the page behave weirdly (I think).

• 3 Behaviours of RTD addons can be changed only in the Read The Docs dashboard

That means a very high level of permission (via RTD) is needed to change that, and completely independent of code in the repository.

• 4 The injected RTD scripts can interact badly with custom CSS/JS, themes, designts etc

Not sure how, so I tried removing some things. And now disabling link preview on the cards.

It feels brittle, but probably is the best I can do for now.

[lubianat]

@jo-mueller the last commit fixes it for me

[jo-mueller]

I'm just seeing that sphinx-design (which is a dependency for this page build) itself supports cards. Maybe that would save ourselves some of the css and java-script tooling here?

Edit Nevermind: Just realized that the grid-item-card is in fact from sphinx design 🙄

Maybe we add ourselves a TODO somewhere to remind ourselves to revisit the code we added here to fix/remove the code we are adding here to resolve the RTD interference? If we host this page ourselves at some point we can then get rid of it.