Write Choice Updates

[gabrielraeder]

• Created homepage
• Configured Sidebar structure
• added extra CSS and JS
• Added a home button on the navbar

[github-actions]

MLCommons CLA bot:
Thank you very much for your submission, we really appreciate it. Before we can accept your contribution, we ask that you sign the MLCommons CLA (Apache 2). Please use this [Google form] (https://forms.gle/Ew1KkBVpyeJDuRw67) to initiate authorization. If you are from an MLCommons member organization, we will request that you be added to the CLA. If you are not from a member organization, we will email you a CLA to sign. For any questions, please contact [email protected].
0 out of 1 committers have signed the MLCommons CLA.
❌ @gabrielraeder
_{You can retrigger this bot by commenting recheck in this Pull Request}

[VukW]

Hi @gabrielraeder!

I've reviewed the feature for displaying images corresponding to each step in the tutorial. On my laptop, it appears as follows:

Windows 11, Chrome 119.0.6045.200, 1920x1080, text size 100%, scale 100%

1. It seems the image size remains fixed regardless of the available space. I suspect this issue didn't arise on your setup due to a higher resolution. Could we adjust the image scale to fit the column space? (Also, I'm unsure about the behavior when the page isn't at full width, leaving limited space for images.)

2. As you demonstrated, the script at

   medperf/docs/scripts/script.js

   Line 1 in 3d1b16f

   const imageSources = [

   determines which image to display based on the absolute Y position. However, varying factors like device types, zoom settings, etc., can alter the layout, causing discrepancies between the text height and the corresponding image. This method also means that any future text updates could disrupt this alignment. Would it be possible to anchor images to specific headers or invisible markers placed at precise locations, instead of relying on absolute Y positions?

3. Currently, not all images correspond accurately to their content, and some sections lack relevant images. Additionally, we need to tweak the content structure for better alignment with the images. I've prepared the necessary text modifications and a new set of images. I can implement these changes myself after resolving the technical issues mentioned above, ensuring the content and image alignment remains consistent across different devices. What are your thoughts on this?

[gabrielraeder]

@VukW ,

1. As the images are supposed to be changed, it wasn't the concern yet to fully configure it, as the layout, size, and other things may change.

2. I will try to find a way to determine the position based on the title. So far, I couldn't with what I found available with MKDocs.

3. Same as 1, as the images placed there now are not supposed to be final. They were used as placeholders just to showcase the idea.

[VukW]

1. My confusion is not in the size of original image, but in the fact that we should zoom image on the client side depending on how much space there is for image column, to eradicate broken layout as on my previous screenshot.
2. I'd propose the following solution:

const imageSources = [
{ header: "overview", image: 1 },  // every header has its text as element Id
{ header: "before-you-start", image: 2 },
...

imageSources.forEach(({ header, image }) => {
  const headerElement = document.getElementById(header)  // find header
  headerTop = headerElement.getBoundingClientRect().top;  // get its top border
  if (headerTop < 400) {    //  change image whenever header crosses this invisible line on the screen
    imageSrc = `https://raw.githubusercontent.com/gabrielraeder/website/main/docs/static/images/workflow/miccai-tutorial${image}.png`;
  }

It's still a dirty solution as it becomes broken when we change headers' text, but at least helps to keep the same behavior on the different devices

3. 👍

[gabrielraeder]

@VukW, similar to what you suggested, I did it based on the header content because when the id contains a number at the start, such as 1. Prepare your Data, the element was not being found. As you commented that it's still a dirty solution, I don't believe there will be a more elegant solution without basing it on hard-coded header content. The first solution was a more elegant solution based on that, but it was broken, as you mentioned.

Other important points: Mkdocs is not responsive and ready for mobile devices, and presenting an image for such devices, we believe would not be ideal. With that in mind, we suggest showing these images flow on screens higher than 1000px, including tablets with side views, laptops, and monitors.

Second, we have available space on bigger screens of 380px for the images, and we would change its size based on media queries to use the most available space for each screen size. Also, suggest making images without backgrounds, making versions of each for light and dark mode. And we would use code to define which image to present also based on the color scheme.

Please share your thoughts about all this. So we can make any new changes that may be required.

[VukW]

@gabrielraeder
writechoiceorg#2

Added my fixes.

1. I have found a better solution for text content <-> image alignment - now images are defined in the specific places of md itself, and js code just extracts src from the necessary image and add it to the sticky container
2. Fixed the css styles to made the image responsive: now it behave properly on any page sizes and any scales on my environment. Check it, please, if everything works on your side as well
   2.1. if the page is too narrow and there is no enough space for the image - it hides;
   2.2. if the screen resolution is too big - MKdocs restricts content area to some reasonable width in the screen center, and image does not leave this area;
   2.3. normally, image takes 35% of content area width
3. Uploaded relevant images to all three tutorials, all stages btw