Improve documentation page and overlay layout
Make the embedded and non-embedded documentation more readable:
* Constrain the prose to a ~44em measure with a calm vertical rhythm
(left-aligned, unitless line-height, consistent paragraph/list
spacing), scoped to the doc pages (main.tutorial), so lines are no
longer viewport-wide on large screens.
* Cap the documentation overlay window (#tutorial) at 72em instead of
spanning ~96% of the viewport, and anchor it to the right so it reads
as a right-hand documentation drawer that leaves the main workspace
(query / results) uncovered. Small viewports still get a full-screen
panel.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Change-Id: Iabdfdc8b03c3713abce89b7ecdea6513190a3cfd
diff --git a/dev/scss/main/main.scss b/dev/scss/main/main.scss
index 21e0596..25493b5 100644
--- a/dev/scss/main/main.scss
+++ b/dev/scss/main/main.scss
@@ -54,6 +54,55 @@
padding-top: 1em;
}
+ // Documentation prose (doc pages carry the "tutorial" class). Without a
+ // measure the content is as wide as the viewport, which on large screens
+ // yields very long, hard-to-read lines; justified text then stretches the
+ // word spacing unevenly. Cap the line length, left-align and give the flow
+ // a calm, consistent vertical rhythm.
+ &.tutorial {
+ p, ul, ol, dl, blockquote, table, pre, details,
+ h2, h3, h4, h5, h6 {
+ max-width: 44em;
+ }
+
+ p, li, dd {
+ text-align: left;
+ line-height: 1.6;
+ }
+
+ // Only set vertical (block) margins here; using the "margin" shorthand
+ // would reset horizontal margins set elsewhere -- e.g. the hanging indent
+ // of p.bibentry in the citation help (margin-left) would be lost.
+ p {
+ margin-block: 0 1em;
+ }
+
+ li {
+ margin-block: .25em;
+ }
+
+ // Tighter list indentation than the ~40px UA default, which is a lot of
+ // space especially on narrow screens.
+ ul, ol {
+ padding-left: 1.5em;
+ }
+
+ // MultiMarkdown renders a list item as "loose" (its text wrapped in a
+ // <p>) when the item carries block content, and "tight" (bare text)
+ // otherwise -- so within one list some labels would end up in a <p> and
+ // others not. Keep those consistent: give list-item paragraphs the list
+ // text's size, and drop the block margin on a leading label paragraph so
+ // a loose item does not look larger/more spaced than its tight siblings.
+ // Following paragraphs in the same item keep their spacing.
+ li p {
+ font-size: inherit;
+ }
+
+ li > p:first-child {
+ margin-block: 0;
+ }
+ }
+
// &.page {
// margin-left: $logo-left-distance + 15px;
// p,
diff --git a/dev/scss/main/tutorial.scss b/dev/scss/main/tutorial.scss
index 44654dd..9fa882f 100644
--- a/dev/scss/main/tutorial.scss
+++ b/dev/scss/main/tutorial.scss
@@ -14,8 +14,13 @@
z-index: 9999;
top: 5%;
bottom: 5%;
- left: 2%;
+ // Anchor the panel to the right and cap its width, so it reads as a
+ // right-hand documentation drawer and leaves the main workspace on the left
+ // uncovered. On narrow viewports it still uses (almost) the full width (see
+ // the media query, which resets left/right/width for a full-screen panel).
+ left: auto;
right: 2%;
+ width: min(96%, 72em);
padding-right: lengths.$right-view-distance;
background-color: colors.$nearly-white;
box-shadow: choose.$choose-box-shadow;
diff --git a/dev/scss/media.scss b/dev/scss/media.scss
index ba6de14..7a1e32a 100644
--- a/dev/scss/media.scss
+++ b/dev/scss/media.scss
@@ -244,7 +244,11 @@
margin-right: lengths.$standard-margin;
&.shifted {
- padding-left: 0;
+ // On mobile the sidebar/logo is not beside the content, so keep the
+ // normal 1rem left padding here (instead of the desktop logo offset)
+ // rather than dropping it to 0 -- otherwise the text is flush to the
+ // left edge and the left/right margins look unbalanced.
+ padding-left: 1rem;
}
}
@@ -367,6 +371,7 @@
border-width: 0;
right: 0;
left: 0;
+ width: auto;
bottom: 0;
top: 0;
padding: 0;