Skip to content

Commit edb5c50

Browse files
przemyslawzalewskiprzemyslawzalewski
authored
Merge pull request #43 from sandstreamdev/improve_docs_page_layout
Improve docs page layout
2 parents 1772438 + 20b1e1f commit edb5c50

File tree

10 files changed

+959
-66
lines changed

10 files changed

+959
-66
lines changed

‎.eslintignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
index.cjs.js
22
index.umd.js
33
.coverage
4+
docs/dist

‎docs/css/docs.css‎

Lines changed: 179 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
11
body {
2-
font-family: "Times New Roman", Times, serif;
3-
height: 100vh;
4-
overflow: hidden;
2+
font-family: system, -apple-system, ".SFNSText-Regular", "San Francisco",
3+
"Roboto", "Segoe UI", "Helvetica Neue", "Lucida Grande", sans-serif;
4+
min-height: 100vh;
55
margin: 0;
66
padding: 0;
7+
display: flex;
8+
line-height: 1.75;
79
}
810

911
.examples .content {
@@ -21,32 +23,48 @@ body {
2123
}
2224

2325
ul {
26+
margin: 0;
27+
padding: 0;
28+
padding-left: 16px;
2429
list-style-type: circle;
2530
}
2631

27-
.std-item {
28-
background: #fafafa;
29-
border: 0.5px solid lightgray;
30-
padding: 8px 16px;
31-
border-radius: 5px;
32-
margin-bottom: 16px;
32+
article {
33+
margin-bottom: 56px;
3334
}
3435

35-
.std-item h2 {
36+
article h2 {
3637
margin-top: 4px;
3738
}
3839

40+
article h3 {
41+
margin-bottom: 0;
42+
}
43+
3944
code {
40-
border-radius: 5px;
45+
font-family: Consolas, "Andale Mono WT", "Andale Mono", "Lucida Console",
46+
"Lucida Sans Typewriter", "DejaVu Sans Mono", "Bitstream Vera Sans Mono",
47+
"Liberation Mono", "Nimbus Mono L", Monaco, "Courier New", Courier,
48+
monospace;
49+
border-radius: 6px;
4150
}
4251

4352
.module-name {
44-
margin-bottom: 4px;
53+
margin: 0;
54+
}
55+
56+
aside .module-name {
57+
position: sticky;
58+
top: 92px;
59+
padding: 0 16px;
4560
}
4661

4762
.module-name,
4863
.name {
49-
font-family: "Courier New", Courier, monospace;
64+
font-family: Consolas, "Andale Mono WT", "Andale Mono", "Lucida Console",
65+
"Lucida Sans Typewriter", "DejaVu Sans Mono", "Bitstream Vera Sans Mono",
66+
"Liberation Mono", "Nimbus Mono L", Monaco, "Courier New", Courier,
67+
monospace;
5068
}
5169

5270
.module-name.selected > a,
@@ -63,60 +81,117 @@ a {
6381
color: black;
6482
}
6583

66-
.toc {
67-
background: #fafafa;
68-
border: 0.5px solid lightgray;
69-
border-radius: 5px;
70-
padding: 8px 16px;
71-
padding-bottom: 16px;
84+
aside {
7285
display: block;
73-
position: absolute;
7486
height: auto;
7587
bottom: 0;
7688
top: 0;
7789
left: 0;
78-
margin: 16px;
79-
width: 208px;
90+
width: 100%;
91+
max-width: 288px;
8092
overflow: auto;
93+
position: sticky;
94+
flex-shrink: 0;
95+
max-height: 100vh;
96+
padding: 0;
97+
box-sizing: border-box;
98+
background: white;
99+
-webkit-overflow-scrolling: touch;
100+
box-sizing: content-box;
101+
border-right: 1px solid lightgray;
81102
}
82103

83-
.row > .content {
84-
display: block;
85-
position: absolute;
86-
height: auto;
87-
bottom: 0;
104+
aside h1 {
105+
position: sticky;
106+
font-size: 1em;
107+
display: flex;
108+
align-items: center;
109+
padding: 0 16px;
110+
margin: 0;
111+
height: 56px;
88112
top: 0;
89-
left: 256px;
90-
right: 0;
91-
margin: 16px;
92-
overflow: auto;
113+
z-index: 2;
114+
background: white;
115+
}
116+
117+
aside h3 {
118+
min-height: 36px;
119+
display: flex;
120+
flex-direction: column;
121+
justify-content: center;
122+
background: white;
123+
border: 1px solid lightgray;
124+
border-left-width: 0;
125+
border-right-width: 0;
126+
margin: 0;
127+
padding: 0;
128+
}
129+
130+
.module {
131+
margin-bottom: 32px;
132+
}
133+
134+
main {
135+
padding: 16px;
136+
width: 100%;
137+
margin: 0 auto;
138+
max-width: 640px;
139+
box-sizing: border-box;
140+
overflow-x: hidden;
141+
display: flex;
142+
flex-direction: column;
143+
justify-content: space-between;
93144
}
94145

95146
.list {
96147
overflow: hidden;
97148
}
98149

99150
.toc-item {
100-
font-family: "Courier New", Courier, monospace;
151+
font-family: Consolas, "Andale Mono WT", "Andale Mono", "Lucida Console",
152+
"Lucida Sans Typewriter", "DejaVu Sans Mono", "Bitstream Vera Sans Mono",
153+
"Liberation Mono", "Nimbus Mono L", Monaco, "Courier New", Courier,
154+
monospace;
155+
156+
min-height: 36px;
157+
display: flex;
158+
flex-direction: column;
159+
justify-content: center;
160+
margin: 0;
161+
padding: 0 16px;
101162
}
102163

103-
.toc-item.selected > a {
164+
.toc-item.selected {
104165
font-weight: bold;
105166
color: #0275d8;
106-
font-size: 18px;
167+
}
168+
169+
aside .module-name:hover,
170+
.toc-item:hover {
171+
background: #f2f2f2;
107172
}
108173

109174
.breadcrumbs {
110-
font-size: 16px;
111-
padding-top: 8px;
175+
background: white;
176+
position: sticky;
177+
top: 0;
178+
background: white;
179+
min-height: 56px;
180+
box-sizing: border-box;
181+
display: flex;
182+
align-items: center;
183+
margin: 0 -16px;
184+
padding: 8px 16px;
185+
flex-wrap: wrap;
112186
}
113187

114188
.breadcrumbs > a {
115189
color: #0275d8;
116190
}
117191

118192
.breadcrumbs > a:hover {
119-
color: black;
193+
color: #0275d8;
194+
text-decoration: underline;
120195
}
121196

122197
.breadcrumbs > span {
@@ -125,14 +200,76 @@ a {
125200

126201
#searchInput {
127202
font-size: 16px;
128-
padding: 4px;
129203
box-sizing: border-box;
130204
width: 100%;
131205
border: none;
132-
border-bottom: solid 1px gray;
206+
box-sizing: border-box;
207+
margin: 0;
208+
min-height: 36px;
209+
position: sticky;
210+
top: 56px;
211+
padding: 0 16px;
212+
z-index: 1;
133213
}
134214

135-
#searchInput:focus {
136-
outline: none;
137-
border-bottom-color: #0275d8;
215+
aside {
216+
position: fixed;
217+
transform: translateX(-100%);
218+
z-index: 1;
219+
}
220+
221+
body.toc-active aside {
222+
transform: translateX(0);
223+
}
224+
225+
.toc-button {
226+
width: 36px;
227+
height: 36px;
228+
display: inline-flex;
229+
justify-content: center;
230+
align-items: center;
231+
padding: 0 !important;
232+
margin-right: 8px;
233+
user-select: none;
234+
margin-left: -10px;
235+
flex-shrink: 0;
236+
cursor: pointer;
237+
}
238+
239+
@media (min-width: 640px) {
240+
.toc-button {
241+
display: none;
242+
}
243+
244+
aside {
245+
position: sticky;
246+
transform: translateX(0);
247+
}
248+
}
249+
250+
footer {
251+
display: flex;
252+
flex-direction: column;
253+
align-items: center;
254+
padding-bottom: 40px;
255+
}
256+
257+
footer a,
258+
footer a:visited {
259+
color: #0275d8;
260+
}
261+
262+
footer a:hover {
263+
color: #0275d8;
264+
text-decoration: underline;
265+
}
266+
267+
.meta a,
268+
.meta a:visited {
269+
color: #0275d8;
270+
}
271+
272+
.meta a:hover {
273+
color: #0275d8;
274+
text-decoration: underline;
138275
}

‎docs/scripts/docs.js‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
/* eslint-env browser */
2+
13
// eslint-disable-next-line no-unused-vars
24
function tryInREPL(event, scope) {
35
var target = event.target;
@@ -22,3 +24,14 @@ function tryInREPL(event, scope) {
2224
source: codeElement.textContent
2325
});
2426
}
27+
28+
// eslint-disable-next-line no-unused-vars
29+
function toggleTableOfContents() {
30+
var className = "toc-active";
31+
32+
if (!document.body.classList.contains(className)) {
33+
document.body.classList.add(className);
34+
} else {
35+
document.body.classList.remove(className);
36+
}
37+
}

‎docs/templates/function.js‎

Lines changed: 31 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ import { scrollTo } from "../utils/scripts.js";
77
import pageTemplate from "./page.js";
88
import last from "../../array/last.js";
99
import reverse from "../../array/reverse.js";
10+
import tocButton from "./tocButton.js";
1011

1112
const { writeFile: writeFileAsync, mkdir: mkdirAsync } = promises;
1213

@@ -25,12 +26,35 @@ const breadcrumb = (name, pathParts) => {
2526
);
2627
}
2728

28-
return `<div class="breadcrumbs">${resultParts.join("<span>/</span>")}</div>`;
29+
return `${resultParts.join("<span>/</span>")}`;
2930
};
3031

3132
const nameFragment = (name, pathParts) =>
3233
name
33-
? `<h3 class="name"><a href="${getPath(pathParts, name)}">${name}</a></h3>`
34+
? `<h3 class="name breadcrumbs">${tocButton}${breadcrumb(
35+
name,
36+
pathParts
37+
)}<span>/</span><a href="${getPath(pathParts, name)}">${name}</a></h3>`
38+
: "";
39+
40+
const blobUrl = "https://github.com/sandstreamdev/std/blob/master";
41+
42+
const sourcePath = (name, partPaths, extension) =>
43+
`${[blobUrl, partPaths, name].join("/")}${extension}`;
44+
45+
const metaFragment = (name, pathParts) =>
46+
name
47+
? `<p class="meta">
48+
<a href="${sourcePath(
49+
name,
50+
pathParts,
51+
".ts"
52+
)}">TypeScript source</a> • <a href="${sourcePath(
53+
name,
54+
pathParts,
55+
".js"
56+
)}">JavaScript source</a>
57+
</p>`
3458
: "";
3559

3660
const descriptionFragment = description => {
@@ -105,18 +129,14 @@ const funcTemplate = (
105129
{ name, description, signature, examples, questions },
106130
pathParts
107131
) => {
108-
const content = `<div class="std-item">
109-
<div>
110-
${breadcrumb(name, pathParts)}
111-
</div>
112-
<div>
113-
${nameFragment(name, pathParts)}
114-
${descriptionFragment(description)}
115-
</div>
132+
const content = `<article>
133+
${nameFragment(name, pathParts)}
134+
${descriptionFragment(description)}
116135
${signatureFragment(signature)}
117136
${examplesFragment(examples, pathParts, name)}
118137
${questionsFragment(questions)}
119-
</div>`.trimLeft();
138+
${metaFragment(name, pathParts)}
139+
</article>`.trimLeft();
120140

121141
return content;
122142
};

0 commit comments

Comments
 (0)