Skip to content

Commit 71c9909

Browse files
DerekNonGenericDerekNonGeneric
authored
📖✨：give the docs an index
📖✨：give the docs an index The page at /docs/ was five paragraphs of Latin, and the home page links to it. Thirteen real pages already published underneath it, reachable only by knowing the URL. Every handbook page carries a `key_point`: one sentence stating the rule it makes. Nothing rendered it. The include that would have, `key-point.liquid`, is called from a layout no page uses. So the index puts each rule beside its name and most lookups end here rather than a page in. Five of the nine handbook pages are placeholders. The index says which, and how many, because on a community site a gap that is named is a job somebody can pick up. The count and the flags are read from the same collection the list is built from, so they cannot disagree with it. Both groups come from collections rather than a typed list. A doc appears by existing, and the four mirrored from OpenINF/.github carry their summaries in the task that generates them, so a regeneration does not drop them. The Edit link on every page under /docs/ pointed at OpenINF/open.inf.is, which does not exist. Pages can now also set their own `description`, which the whole site had been filling with one site-wide sentence. ♿🔧：lift the links on the ink bands off the ink The masthead's own rules had the right colours all along: parchment for the GitHub row, parchment at 82% for the line about the Code of Conduct. Neither reached the page. `.home main a` is (0,1,2) and carries the deep teal meant for links on parchment; a rule naming only the row it styles is (0,1,1) and loses to it. On the ink that teal reads 2.62:1, the same number and the same cause as the navbar links. The band now sets a legible colour for any link inside it, and the rules that differ from it carry `main` too, so a link added to the masthead later starts readable rather than starting at 2.62:1. The docs page had it in `.invite`, where the link now takes the mono and the parchment `.join-row` gives the home page's equivalent link, both boxes being the same box. 13.97:1, 9.72:1, and 12.78:1. Signed-off-by: Derek Lewis <DerekNonGeneric@inf.is> Assisted-by: Claude-Code:claude-opus-5 Assisted-by: Claude-Code:claude-fable-5 PR-URL: #1841
1 parent a362653 commit 71c9909

20 files changed

Lines changed: 575 additions & 61 deletions

‎_assets/styles/_custom.scss‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
11
// Custom Styles
22

3+
// The navbar is fixed, so an anchor lands behind it without this. The extra
4+
// room keeps the target clear of the bar rather than flush against it.
5+
html {
6+
scroll-padding-top: calc(#{$navbar-height} + 1rem);
7+
}
8+
39
main {
410
min-height: 100%;
511
}

‎_assets/styles/_docs.scss‎

Lines changed: 358 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,358 @@
1+
@use 'sass:color';
2+
3+
// The docs index: what is written, and what is still open.
4+
5+
// This page reads wider than the 48ch column the rest of the site uses, so it
6+
// sets its own width and its own offset under the fixed navbar. Colours come
7+
// from _sublime-theme.scss; $docs-muted is the tone _home.scss gives secondary
8+
// copy, so the two pages read alike.
9+
10+
$docs-wrap: 1200px;
11+
$docs-gutter: clamp(1rem, 4vw, 3rem);
12+
$docs-link: shade-color($primary, 25%);
13+
$docs-primary-tint: tint-color($primary, 30%);
14+
$docs-muted: #4b433c;
15+
$docs-hairline: rgb(167 151 139 / 55%);
16+
17+
// A pale wash with deep-shade text, so the chip clears AA at this size.
18+
$docs-flag-bg: tint-color($quaternary, 88%);
19+
$docs-flag-text: shade-color($quaternary, 25%);
20+
21+
// Scoped to `main` to keep the resets off the navbar and footer, which are
22+
// its siblings under the same body class. The padding replaces what
23+
// `main > .container` gives the footer elsewhere.
24+
.docs main {
25+
padding-bottom: 104px;
26+
}
27+
28+
.docs main h1,
29+
.docs main h2,
30+
.docs main p,
31+
.docs main dl,
32+
.docs main dd,
33+
.docs main ul {
34+
margin: 0;
35+
}
36+
37+
.docs main ul {
38+
padding: 0;
39+
list-style: none;
40+
}
41+
42+
.docs main a {
43+
color: $docs-link;
44+
}
45+
46+
.docs main :focus-visible {
47+
outline: 2px solid $body-color;
48+
outline-offset: 2px;
49+
}
50+
51+
.docs .wrap {
52+
max-width: $docs-wrap;
53+
padding-inline: $docs-gutter;
54+
margin-inline: auto;
55+
}
56+
57+
/* --- Head -------------------------------------------------------------- */
58+
59+
// Ink, so it carries on from the navbar rather than leaving a pale band
60+
// between the two.
61+
.docs-head {
62+
padding-top: calc(#{$navbar-height} + clamp(2rem, 5vw, 3.5rem));
63+
padding-bottom: clamp(2.25rem, 5vw, 3.5rem);
64+
color: $body-bg;
65+
background-color: $body-color;
66+
}
67+
68+
.docs-head :focus-visible {
69+
outline-color: $body-bg;
70+
}
71+
72+
.docs-head-grid {
73+
display: grid;
74+
grid-template-columns: minmax(0, 1.4fr) minmax(0, 0.85fr);
75+
gap: clamp(2rem, 5vw, 4rem);
76+
align-items: start;
77+
}
78+
79+
// _custom.scss draws a rule after every h1. Beside a two-column grid it
80+
// would stop at this column's edge, so it is off here.
81+
.docs-title {
82+
display: block;
83+
font-size: clamp(1.875rem, 4.5vw, 2.75rem);
84+
font-weight: 700;
85+
line-height: 1.08;
86+
letter-spacing: -0.02em;
87+
}
88+
89+
.docs-title::after {
90+
content: none;
91+
}
92+
93+
.docs-lede {
94+
max-width: 42ch;
95+
margin-top: 1rem !important;
96+
font-size: clamp(1rem, 1.6vw, 1.0625rem);
97+
line-height: 1.6;
98+
color: rgb(231 231 214 / 76%);
99+
}
100+
101+
/* --- Head: the invite -----------------------------------------------
102+
The shape `.join` has on the home page, carrying the handbook's own gap.
103+
Both branches read the count the list further down is built from.
104+
*/
105+
106+
.invite {
107+
padding: 1.25rem 1.375rem;
108+
background-color: rgb(231 231 214 / 4%);
109+
border: 1px solid rgb(231 231 214 / 20%);
110+
}
111+
112+
.invite-eyebrow {
113+
font-family: $font-family-monospace;
114+
font-size: 0.6875rem;
115+
color: $tertiary;
116+
text-transform: uppercase;
117+
letter-spacing: 0.08em;
118+
}
119+
120+
.invite-title {
121+
display: flex;
122+
flex-wrap: wrap;
123+
gap: 0.5rem;
124+
align-items: baseline;
125+
margin-top: 0.625rem !important;
126+
font-size: 1.1875rem;
127+
font-weight: 700;
128+
line-height: 1.3;
129+
color: $body-bg;
130+
}
131+
132+
.invite-num {
133+
font-family: $font-family-monospace;
134+
font-size: clamp(2.25rem, 5vw, 2.75rem);
135+
line-height: 0.9;
136+
color: $docs-primary-tint;
137+
}
138+
139+
.invite-what {
140+
margin-top: 0.75rem !important;
141+
font-size: 0.9375rem;
142+
line-height: 1.6;
143+
color: rgb(231 231 214 / 70%);
144+
}
145+
146+
.invite-row {
147+
padding-top: 0.875rem;
148+
margin-top: 1rem !important;
149+
border-top: 1px solid rgb(231 231 214 / 16%);
150+
}
151+
152+
// Links on the ink. `.docs main a` is (0,1,2), so a band rule needs `main`
153+
// to reach them.
154+
.docs main .docs-head a {
155+
color: $body-bg;
156+
}
157+
158+
// The treatment `.join-row a` gives the home page's equivalent link.
159+
.docs main .invite-row a {
160+
font-family: $font-family-monospace;
161+
font-weight: 700;
162+
color: $body-bg;
163+
}
164+
165+
/* --- Shared section furniture ------------------------------------------ */
166+
167+
.docs .band {
168+
padding-block: clamp(2.5rem, 6vw, 4rem);
169+
}
170+
171+
// The handbook is the substance of this page, so it sits on its own ground.
172+
.docs .band-quiet {
173+
background-color: color.mix($tertiary, $body-bg, 12%);
174+
border-block: 1px solid $docs-hairline;
175+
}
176+
177+
.docs .section-head {
178+
display: flex;
179+
flex-wrap: wrap;
180+
gap: 0.5rem 1rem;
181+
align-items: baseline;
182+
justify-content: space-between;
183+
padding-bottom: 0.75rem;
184+
border-bottom: 2px solid $body-color;
185+
}
186+
187+
.docs .section-title {
188+
font-size: 1.125rem;
189+
font-weight: 700;
190+
letter-spacing: -0.01em;
191+
}
192+
193+
.docs .section-more {
194+
font-family: $font-family-monospace;
195+
font-size: 0.8125rem;
196+
}
197+
198+
.docs .section-count {
199+
font-family: $font-family-monospace;
200+
font-size: 0.8125rem;
201+
color: $docs-muted;
202+
text-transform: uppercase;
203+
letter-spacing: 0.06em;
204+
}
205+
206+
/* --- Taking part --------------------------------------------------------
207+
A plain divided list: process and community links, the same kind of thing
208+
as the home page's "How we work".
209+
*/
210+
211+
.docs .part-list {
212+
display: grid;
213+
grid-template-columns: repeat(2, minmax(0, 1fr));
214+
gap: 0 clamp(1.5rem, 4vw, 3rem);
215+
margin-top: 1.75rem !important;
216+
}
217+
218+
.docs .part-item {
219+
padding-block: 1.375rem;
220+
border-bottom: 1px solid $docs-hairline;
221+
}
222+
223+
.docs .part-name {
224+
font-size: 1.0625rem;
225+
font-weight: 700;
226+
}
227+
228+
.docs .part-what {
229+
margin-top: 0.375rem !important;
230+
font-size: 0.9375rem;
231+
line-height: 1.6;
232+
color: $docs-muted;
233+
}
234+
235+
/* --- The handbook -------------------------------------------------------
236+
Alphabetical, one row per rule, name and point side by side so the names
237+
read as an index. The numeral uses `.area-num`'s recipe from the home page.
238+
*/
239+
240+
.docs .handbook-lede {
241+
max-width: 60ch;
242+
margin-top: 1.25rem !important;
243+
font-size: 0.9375rem;
244+
line-height: 1.65;
245+
color: $docs-muted;
246+
}
247+
248+
.docs .rule-list {
249+
margin-top: 1.75rem !important;
250+
}
251+
252+
.docs .rule {
253+
display: grid;
254+
grid-template-columns: minmax(0, 19rem) minmax(0, 1fr);
255+
gap: 0.25rem 2rem;
256+
padding-block: 0.875rem;
257+
border-bottom: 1px solid rgb(167 151 139 / 35%);
258+
}
259+
260+
.docs .rule:first-child {
261+
border-top: 1px solid rgb(167 151 139 / 35%);
262+
}
263+
264+
// A grid, so the numeral keeps its own column and stays beside the first
265+
// line of a title long enough to wrap.
266+
.docs .rule-name {
267+
display: grid;
268+
grid-template-columns: 1.375rem minmax(0, 1fr);
269+
gap: 0.5rem;
270+
align-items: baseline;
271+
font-size: 0.9375rem;
272+
font-weight: 700;
273+
}
274+
275+
.docs .rule-num {
276+
font-family: $font-family-monospace;
277+
font-size: 0.75rem;
278+
font-weight: 400;
279+
color: $docs-link;
280+
}
281+
282+
.docs .rule-heading {
283+
display: flex;
284+
flex-wrap: wrap;
285+
gap: 0.5rem;
286+
align-items: baseline;
287+
}
288+
289+
.docs .rule-point {
290+
font-size: 0.9375rem;
291+
line-height: 1.6;
292+
}
293+
294+
// The chip carries the state in text, so it does not rest on colour alone.
295+
.docs .rule-flag {
296+
padding: 0.0625rem 0.4375rem;
297+
font-family: $font-family-monospace;
298+
font-size: 0.6875rem;
299+
font-weight: 400;
300+
color: $docs-flag-text;
301+
text-transform: uppercase;
302+
letter-spacing: 0.06em;
303+
background-color: $docs-flag-bg;
304+
}
305+
306+
.docs .handbook-gap {
307+
max-width: 60ch;
308+
margin-top: 1.5rem !important;
309+
font-size: 0.9375rem;
310+
line-height: 1.65;
311+
color: $docs-muted;
312+
}
313+
314+
/* --- Not here yet --------------------------------------------------------
315+
Quieter than the sections above: a heading at their size would promise a
316+
third pillar the page does not have.
317+
*/
318+
319+
.docs .band-tail {
320+
padding-block: clamp(1.5rem, 3vw, 2rem);
321+
}
322+
323+
.docs .tail-title {
324+
font-family: $font-family-monospace;
325+
font-size: 0.75rem;
326+
font-weight: 700;
327+
color: $docs-muted;
328+
text-transform: uppercase;
329+
letter-spacing: 0.08em;
330+
}
331+
332+
.docs .tail-what {
333+
max-width: 60ch;
334+
margin-top: 0.625rem !important;
335+
font-size: 0.9375rem;
336+
line-height: 1.65;
337+
color: $docs-muted;
338+
}
339+
340+
/* --- Narrow -------------------------------------------------------------- */
341+
342+
@media (width < 960px) {
343+
.docs-head-grid {
344+
grid-template-columns: minmax(0, 1fr);
345+
}
346+
}
347+
348+
@media (width < 760px) {
349+
.docs .part-list {
350+
grid-template-columns: minmax(0, 1fr);
351+
}
352+
353+
// The name column stops earning its width once the point beside it wraps.
354+
.docs .rule {
355+
grid-template-columns: minmax(0, 1fr);
356+
gap: 0.375rem;
357+
}
358+
}

‎_assets/styles/_home.scss‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -270,7 +270,13 @@
270270
color: rgb(231 231 214 / 70%);
271271
}
272272

273-
.join-row a {
273+
// Links on the ink. `.home main a` is (0,1,2), so a band rule needs `main`
274+
// to reach them.
275+
.home main .masthead a {
276+
color: var(--parchment);
277+
}
278+
279+
.home main .join-row a {
274280
font-family: var(--mono);
275281
font-weight: 700;
276282
color: var(--parchment);
@@ -282,7 +288,8 @@
282288
color: rgb(231 231 214 / 58%);
283289
}
284290

285-
.join-coc a {
291+
// Same weight as the rule above it, so this stays below it in the file.
292+
.home main .join-coc a {
286293
color: rgb(231 231 214 / 82%);
287294
}
288295

0 commit comments

Comments
 (0)