Skip to content

Make the layout of runnable code examples vertical - #1401

Draft
NathanLovato wants to merge 4 commits into
mainfrom
nathan/runnable_example_layout_change
Draft

NathanLovato wants to merge 4 commits into
mainfrom
nathan/runnable_example_layout_change

Conversation

@NathanLovato

@NathanLovato NathanLovato commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

This is to give code more horizontal space, remove excessive horizontal scroll bars on code listings, and this also makes the code listings size automatically.

This PR is a quick prototype for testing and review before committing to more changes.

Things to do and review:

  1. Ensure there's enough space at the bottom of code listings. This could be either by ensuring there's an empty line procedurally or applying some content margin if possible.
  2. Confirm the layout, if we always want it vertical like that, or if we want to swap some elements or be able to mix things up.

@NathanLovato

Copy link
Copy Markdown
Contributor Author

Notes from S. on things that need work:

  • Grouping. It becomes more important with the rows than it used to be with the columns for reasons like: scrolling, and the possibility of having a second code block in the vicinity, not connected to the demo (or debugger).
  • Padding instead of code line. I'm wondering if you can add default padding to the automatically sized code block rather than add an empty line of code.

By grouping, I mean an element that indicates, this demo, this code blog (and this debugger) are together. Or if you're partially scrolled down, it tells you: This is not standalone.

@NathanLovato

NathanLovato commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor Author

Quick sketch to address both points:

image

@NathanLovato

Copy link
Copy Markdown
Contributor Author

Without separation line:
image

@NathanLovato

NathanLovato commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor Author

Current look

Snippet with output.

image

Visual example

image

Issues and regressions observed right now

At this point it's working more or less across the app, technically speaking. Has at least these issues, taking note of them (but first, the layout needs vetting):

  • Output font switches from normal to mono space when going from nothing printed yet to the output. This grows the text and the output panel and pushes the panel down a little.
  • There's still a bit of visual misalignment between the variables, label, output, and the value at the right when both debugger and output are visible. Especially when the output is only
  • When stepping through the code, the background highlight of the code edit has several issues:
    • The color is too bright.
    • Once it's visible, clicking on any line changes the highlighted line. That highlight should not change with the cursor. It's only meant to highlight the last line that was executed and that updated the variables display.
  • The variables that have an underline in debugged examples, the underline can be a bit misplaced and leak into the next character. It's not aligned super well to the text at the moment, and also the text that appears above on Hover is a bit imbalanced. But for that, one thing to think about is whether to keep those, like how useful they are, because we have short snippets and we have a view of the variables in the panel at the top.
  • Fonts for the output panel are too small. They are substantially smaller than the rest of the text. Initially, I found that the variables in output label, as they were before, were too large, but it's more that the default text across the app is pretty large with the default setting on a display like mine.
  • Output currently grows the output panel and pushes the code listing and buttons down. We may still allow it to grow, but to avoid having too much empty space early on. But after a couple items, it should start to offer a scrolling view.
  • Several examples only use the demo panel with no code snippet. But to make the layout work vertically, the code currently removes the bottom rounded corners from the demo. So, for example, in L11, there's an example that has sharp bottom corners when they should be rounded to fit the frame.
  • The background does not look very good. Consider reusing something like diagrams from GDSchool.
  • The demo will sometimes be misplaced now that the display space is more horizontal. It's okay overall and can be tweaked in the few cases where it's problematic.
    • This is for a separate issue, but we can probably find a way to better control the placement of visual examples in the view, perhaps by giving them bounds through an exported property, or just a pivot point and offset.

Content issues (probably more to find, some to offload to separate issues):

  • (pre-existing bug): One example in L22 has an extra added line only at runtime. In "Using arrays as stacks"
  • Some code snippets have inline comments that are barely readable and that should not be part of the examples.

@NathanLovato
NathanLovato force-pushed the nathan/runnable_example_layout_change branch from 065a81d to 81a2930 Compare October 2, 2026 18:36
This is to give code more horizontal space, remove excessive horizontal scroll bars on code listings, and this also makes the code listings size automatically
See the running app to see the result. This is to give a nicer vertical
layout with grouping to runnable examples. It accounts for different
situations, like if we have a debug view of variable state or not.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant