bug: Deep-linking scrolls to the wrong target when page includes referenced codeblocks

[hamza-m-masood]

Example

When I go to this link: https://docs.camunda.io/docs/next/self-managed/setup/deploy/amazon/amazon-eks/eks-terraform/#opensearch-module-setup

I am brought to the PostgreSQL module setup and not the OpenSearch module setup.

More detail

As mentioned in #4754 (comment), this is a layout shift issue, due to referenced codeblocks on the page changing their height after the initial page load.

[conceptualshark]

I think this is an issue of how and at what time the page/tabs are actually rendered, so not sure there is an easy fix - @pepopowitz can you confirm? When I open this link in an incognito window the bouncing as things load is more apparent.

[pepopowitz]

this is a layout shift problem, due to the referenced codeblocks on the page. On my end I saw the page initially load at the OpenSearch module section, very briefly, before it scrolled to the PostgreSQL section. The reference codeblocks load purely client-side, and the post-load scrolling is a result of them filling in their content.

The fix for these problems is to match the initial page load height to the post-client-side height. I suppose this could be done by rendering the blocks with a specific initial height and then restricting the final height of referenced codeblocks to match, potentially requiring scrolling or blank lines within the blocks.

But this functionality is coming from a plugin, and it would mean either contributing to what appears to be a relatively quiet project, or forking or patching.

I don't personally have the appetite for this, given the relatively low ROI. I am open to persuasion, if others feel differently (cc @akeller).

Perhaps this is also a nudge for us to look at the amount of content on that page. Questions that I pose but don't have answers to -- could it be broken up into multiple pages? Do we want to only link to large codeblocks instead of including them? In general I think reorganizing the content here would be a much quicker fix, if the deep-link functionality is the problem we're looking to solve.

FYI I'm going to edit the title of this issue, to describe the problem more specifically -- I have a feeling we'll run into this issue again in other docs.

[akeller]

I don't personally have the appetite for this, given the relatively low ROI. I am open to persuasion, if others feel differently (cc @akeller).

Perhaps this is also a nudge for us to look at the amount of content on that page. Questions that I pose but don't have answers to -- could it be broken up into multiple pages? Do we want to only link to large codeblocks instead of including them? In general I think reorganizing the content here would be a much quicker fix, if the deep-link functionality is the problem we're looking to solve.

Huge +1 to all of this. @conceptualshark is reviewing and refactoring this page on your radar?

[conceptualshark]

These pages are under active development by infraex, so I'd like to hold off on any content restructuring until they're brought up-to-date. I did make myself a ticket to pick up this work again when the new reference architecture work is complete: https://github.com/camunda/developer-experience/issues/439