DM-44542: Two column layout #49
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
We've "vendored" sphinx-basic-ng into the Technote project itself. This is to prepare for changing the technote theme to a two column layout.
This lets us drop the skeleton.css originally from sphinx-basic-ng and folds it into the layout.scss module that's providing out overrides of the layout styling. The next step is to consolidate the styling. Or perhaps even overhaul layout to meet our goals of a two-column layout.
This are useful for regular sphinx sites, but will be unused for single-page technotes.
This dramatically pares back the complexity of the layout template and drops extraneous sections. We'll use this as a good starting point for a responsive grid layout for technote.
This is a two column / two row grid so that the page outline can be in its own grid area. It's mobile first, so in a media query we assign elements to their grid areas. This is so much more elegant than the complex media queries we had before.
In mobile, take the contents outline out of the grid and instead display it as a fullscreen modal.
Style the button. For drop shadows, I'm using box-shadow tokens derived from Josh Comeau's https://www.joshwcomeau.com/shadow-palette/
The easiest way to let the content column smoothly increase in size up to a max size of 72ch is with another wrapper div so that the grid column can just take the excess space.
This button background shouldn't be the text background colour because the text doesn't toggle to white in dark mode.
This idea is from https://www.joshwcomeau.com/css/full-bleed/ to create a grid with whitespace columns that a full-bleed element can spill into by changing their grid columns. This didn't end up working because the full-bleed blocks are embedded by Sphinx inside hierarchical section elements. This means that potential full-bleed images aren't direct children of the grid container, and therefore aren't part of the grid layout calculation.
Note that not only is negative margin necessary, but we also need to reset the max-width of blocks that are normally set to 100%, like img.
jonathansick
force-pushed
the
tickets/DM-44542
branch
from
e70913e to
13ee53b
Compare
This is a checkpoint on progress towards making tables work with the .technote-wide-content class. Need to: - Check that mobile still works - Check that images/image figures still work - Check that code blocks work
The direct link to their pygments overwriting code no longer resolves, so made a more general link.
The key for getting the mobile view to work is to set an explicit width on the table in mobile so that the overflow scrolling would work. Otherwise the table would push the entire content column to be wider than the viewport.
Do this by making the contents area max out to 100vh so that it scrolls independently of the sidebar.
This change makes it so that scrolling to view more of the contents outline in desktop will not cause the content to shift. The logo section is always sticky to the top of the technote.
The goal here is to apply a negative margin to Sphinx block elements like code blocks and admintions so that their text content lines up with the body text. If they have a border or background, then their container needs to have padding big enough to show this overhang (this is a side-effect of needing to set the overflow property on the article to support independent scrolling). For this to work reliably, I'm creating a new custom property so capture this dimension so that it can be used reliably and consistently for both the padding on article and the negative margin on the block elements.
- Create a CSS container called technote-article on the article element - Use that container to reduce the gap between headings and their content in mobile views.
This was breaking code blocks that didn't have captions. It turns out that we never needed this overflow-x on .technote-wide-content because .highlight already includes it. So instead, only add the overflow specifically to tables with wide content.
Need to factor in the negative margin applied to code blocks and also the full padding around the page 2x tn-layout-container-padding
When the code block is full width we still want the caption's text to be constrained to the width of the text block for readability.
With the CSS grid change this was broken, likely because of content order. The higher z-index ensures that the contents overlay appears over the content.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This is a significant PR to technote's theming system. The main goal is to switch to a two-column layout so that wide tables and images can overflow to the right.
To do this we're replacing all the layout from sphinx-basic-ng with a simpler CSS grid. In mobile views, the contents outline becomes a modal popover that's toggled with a button.
Additionally, we've implemented a
technote-wide-contentclass, that, when set by a user on a block element, allows that element to bleed into the whitespace to the right of the content column. Tables and code blocks still scroll horizontally if they overflow their container.CleanShot.2024-06-20.at.15.14.00-converted.mp4