search

espruino / EspruinoDocs

See http://espruino.com for the complete Espruino Documentation - many links in this repository will not work
http://www.espruino.com/
Other
253 stars 282 forks source link

Reference pages layout improvements #703

Closed mariusGundersen closed 7 months ago

mariusGundersen commented 7 months ago

The css for the layout of the reference pages could be improved using new and modern css. Currently the page content is in a div#mainscroller with position:absolute. This makes navigating back after following a local link not work properly. It could work if instead the sidebar had position:fixed and the top bar position:sticky. Or maybe use a grid and have normal overflow. It could be improved.

I think this is also what makes the page very slow to load. It's a very big page, and having that much content inside a positioned absolute div might be a problem.

Another problem is that the header has a margin at the bottom that covers up the top of the content below it. This makes it not possible to click on things at the top of the page: image

Another small problem is that the id of a class, for example Array is different in the sidebar (where it is #Array) and in the title in the main page (where it is #t_Array). I'm not sure if this is intentional, but it seems like the heading points to the sidebar entry and the sidebar entry points to the header.

I tried to find the css and html layout for the reference page to improve it, but couldn't find it. Is it hosted somewhere else?

gfwilliams commented 7 months ago

The actual reference is created in https://github.com/espruino/Espruino/blob/master/scripts/build_board_docs.py - or via make docs - it's called from https://github.com/espruino/EspruinoDocs/blob/master/build.sh#L31

But the whole website isn't public I'm afraid - but to get the page we basically just shove the generated file inside the attached wrapper.

If you're happy to make some changes to the wrapper to get this working differently that'd be really helpful - but it's used for the whole website, so I don't really want to find it's something that's broken everything.

it seems like the heading points to the sidebar entry and the sidebar entry points to the header.

That's the idea... People do use the reference html file on its own (in which case the sidebar is at the top, so it can be handy to flick to and fro)

main-template.txt

mariusGundersen commented 7 months ago

It looks like most of the changes can be done in the carousel.css file and the sitewide.js file. I noticed now that the table of contents is moved into the sidebar using js. That isn't really needed with the following css rule:

@media (min-width: 992px) {
  #contents {
    position: fixed;
    top: 50px;
    left: 0;
    bottom: 0;
    overflow-y: auto;
    overflow-x: hidden;
    width: 300px;
  }

  #maincontent:has(#contents) {
    margin-left: 300px;
  }
}

This way you can remove all the wrapping divs and have just 

<body>
  <div id="header">...</div>
  <div id="maincontent">...</div>
</body>

The result is that the ToC is shown in the sidebar on desktop and at the top of the page on mobile devices.

The header (.navbar-wrapper) should have the rule position: sticky rather than position:absolute, and .navbar-wrapper .navbar should have margin-bottom: 0.

gfwilliams commented 7 months ago

Thanks! I've just pulled those changes in, and the reference appears to load a lot faster now it doesn't rearrange the divs in JS.

I haven't got rid of the content div yet though as I seem to recall that bootstrap kind of expected it and I think it might mess up some of the rest of the website.

mariusGundersen commented 7 months ago

There is some bootstrap grid layout code that isn't strictly necessary, since the grid only has a single column, given that the sidebar is positioned using fixed. It's also from bootstrap 3 which had to rely on float and hacks in order to get layouts that are now pretty easy to do with grid and flexbox.