Skip to content

Commit 776e7e5

Browse files
GeoffreyBoothGeoffreyBooth
authored
Docs improvements (#5042)
* Move analytics initialization into docs.coffee * Bump Bootstrap and CodeMirror versions * Update output * Merge CodeMirror styles * Update CodeMirror styles * Better flexbox layout for docs, including flex auto-sized sidebar and main column * Minor styling fixes for Edge * Fix scrollspy for new layout * Update output * Clicking on the CoffeeScript logo in the navbar should scroll to top; fix main column width on mobile * Update output
1 parent 871079b commit 776e7e5

File tree

11 files changed

+386
-291
lines changed

11 files changed

+386
-291
lines changed

‎docs/v2/index.html‎

Lines changed: 259 additions & 217 deletions
Large diffs are not rendered by default.

‎documentation/site/body.html‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,11 @@
33
<%= include('try.html') %>
44

55
<div class="container-fluid" id="top">
6-
<div class="row flex-nowrap">
7-
<nav class="sidebar col-lg-3 bg-ribbed-light">
6+
<div class="row flex-nowrap main-row">
7+
<nav class="sidebar bg-ribbed-light">
88
<%= include('sidebar.html') %>
99
</nav>
10-
<main class="main col-lg-9 ml-auto">
10+
<main class="main">
1111
<header class="d-none d-lg-block">
1212
<p class="title-logo">
1313
<%= include('logo.svg') %>

‎documentation/site/code.css‎

Lines changed: 74 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,15 @@
1-
/* Adapted from https://github.com/FarhadG/code-mirror-themes/blob/master/themes/twilight.css */
1+
/* Adapted from https://github.com/FarhadG/code-mirror-themes/blob/master/themes/twilight.css and https://github.com/codemirror/CodeMirror/blob/master/theme/twilight.css */
2+
3+
/* CodeMirror general styling */
24

35
.CodeMirror,
46
.placeholder-code {
7+
/* https://codemirror.net/demo/resize.html */
8+
height: auto;
9+
background: transparent;
10+
font-family: 'Roboto Mono';
11+
font-weight: 400;
12+
line-height: 1.25;
513
letter-spacing: 0.3px;
614
color: #f8f8f8;
715
/* Prevent mobile Safari from zooming in on our code editors; the code is 16px naturally, but somehow being explicit about it prevents the zooming */
@@ -10,7 +18,7 @@
1018
@media (min-width: 768px) {
1119
.CodeMirror,
1220
.placeholder-code {
13-
font-size: 90%; /* Matching Bootstrap’s font size for code, which calculates to 14.4px */
21+
font-size: 87.5%; /* Matching Bootstrap’s font size for code, which calculates to 14.4px */
1422
}
1523
}
1624
.CodeMirror-lines {
@@ -21,6 +29,13 @@
2129
margin-bottom: 1.37em;
2230
white-space: pre-wrap;
2331
}
32+
.CodeMirror pre,
33+
pre.placeholder-code {
34+
line-height: 1.4em;
35+
}
36+
.CodeMirror-code:focus {
37+
outline: none;
38+
}
2439
div.CodeMirror-cursor {
2540
border-left: 3px solid #f8f8f8;
2641
}
@@ -30,27 +45,18 @@ div.CodeMirror-cursor {
3045
.CodeMirror-selected {
3146
background: #ddf0ff33;
3247
}
33-
.cm-comment,
34-
.placeholder-code .comment {
35-
font-style: italic;
36-
color: #5f5a60;
37-
}
48+
49+
/* Syntax highlighting */
50+
3851
.cm-keyword,
3952
.placeholder-code .keyword {
4053
color: #cda869;
4154
}
42-
.cm-string,
43-
.placeholder-code .string {
44-
color: #8f9d6a;
45-
}
46-
.cm-property,
47-
.placeholder-code .attribute {
48-
color: #dad085;
49-
}
5055
.cm-atom {
5156
color: #dad085;
5257
}
5358
.cm-number,
59+
.cm-meta,
5460
.placeholder-code .number,
5561
.placeholder-code .built_in,
5662
.placeholder-code .builtin-name,
@@ -61,6 +67,18 @@ div.CodeMirror-cursor {
6167
.placeholder-code .link {
6268
color: #dad085;
6369
}
70+
.cm-def {
71+
color: #f8f8f8;
72+
}
73+
span.cm-variable-2,
74+
span.cm-tag {
75+
color: #f8f8f8;
76+
}
77+
span.cm-variable-3,
78+
span.cm-def,
79+
span.cm-type {
80+
color: #f8f8f8;
81+
}
6482
.cm-operator,
6583
.placeholder-code .punctuation,
6684
.placeholder-code .symbol,
@@ -69,9 +87,50 @@ div.CodeMirror-cursor {
6987
.placeholder-code .operator {
7088
color: #cda869;
7189
}
90+
.cm-comment,
91+
.placeholder-code .comment {
92+
font-style: italic;
93+
color: #5f5a60;
94+
}
95+
.cm-string,
96+
.cm-string-2,
97+
.placeholder-code .string {
98+
color: #8f9d6a;
99+
}
100+
.cm-property,
101+
.placeholder-code .attribute {
102+
color: #dad085;
103+
}
104+
.cm-builtin {
105+
color: #cda869;
106+
}
107+
.cm-tag {
108+
color: #997643;
109+
}
110+
.cm-attribute {
111+
color: #d6bb6d;
112+
}
113+
.cm-header {
114+
color: #FF6400;
115+
}
116+
.cm-hr {
117+
color: #AEAEAE;
118+
}
119+
.cm-link {
120+
color: #ad9361;
121+
font-style: italic;
122+
text-decoration: none;
123+
}
124+
.cm-error {
125+
border-bottom: 1px solid rgba(142, 22, 22, 0.67);
126+
}
72127

73128
/* Uneditable code blocks are inverted, so use darker versions of the above */
74129

130+
.uneditable-code-block code {
131+
padding: 0;
132+
}
133+
75134
.uneditable-code-block .comment {
76135
font-style: italic;
77136
color: #837B85;

‎documentation/site/docs.coffee‎

Lines changed: 19 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,18 @@
11
unless window.location.origin # Polyfill `location.origin` for IE < 11
22
window.location.origin = "#{window.location.protocol}//#{window.location.hostname}"
33

4+
5+
# Initialize Google Analytics
6+
window.GA_TRACKING_ID = 'UA-106156830-1'
7+
window.dataLayer ?= []
8+
window.gtag = ->
9+
window.dataLayer.push arguments
10+
return
11+
window.gtag 'js', new Date()
12+
window.gtag 'config', window.GA_TRACKING_ID
13+
14+
15+
# Initialize the CoffeeScript docs interactions
416
$(document).ready ->
517
# Mobile navigation
618
toggleSidebar = ->
@@ -21,14 +33,14 @@ $(document).ready ->
2133

2234
# Initialize Scrollspy for sidebar navigation; https://getbootstrap.com/docs/4.0/components/scrollspy/
2335
# See also http://www.codingeverything.com/2014/02/BootstrapDocsSideBar.html and http://jsfiddle.net/KyleMit/v6zhz/
24-
$('body').scrollspy
36+
$('.main').scrollspy
2537
target: '#contents'
2638
offset: Math.round $('main').css('padding-top').replace('px', '')
2739

2840
initializeScrollspyFromHash = (hash) ->
2941
$("#contents a.active[href!='#{hash}']").removeClass 'show'
3042

31-
$(window).on 'activate.bs.scrollspy', (event, target) -> # Why `window`? https://github.com/twbs/bootstrap/issues/20086
43+
$('.main').on 'activate.bs.scrollspy', (event, target) ->
3244
# We only want one active link in the nav
3345
$("#contents a.active[href!='#{target.relatedTarget}']").removeClass 'show'
3446
$target = $("#contents a[href='#{target.relatedTarget}']")
@@ -165,6 +177,11 @@ $(document).ready ->
165177
toggleTry yes
166178
$('[data-close="try"]').click closeTry
167179

180+
$('[data-action="scroll-to-top"]').click (event) ->
181+
return if $('#try').hasClass('show')
182+
$('.main')[0].scrollTop = 0
183+
setTimeout clearHash, 10
184+
168185
clearHash = ->
169186
window.history.replaceState {}, document.title, window.location.pathname
170187

‎documentation/site/docs.css‎

Lines changed: 22 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -79,14 +79,18 @@ button:focus, .navbar-dark .navbar-toggler:focus {
7979
}
8080

8181

82+
/*
83+
* Layout; based on https://codepen.io/Sphinxxxx/pen/WjwbEO
84+
*/
85+
.main-row {
86+
height: calc(100vh - 3.5rem);
87+
}
88+
8289
/*
8390
* Sidebar
8491
*/
8592

8693
.sidebar {
87-
position: fixed;
88-
top: 3.5em;
89-
height: calc(100% - 3.5rem);
9094
/* Scrollable contents if viewport is shorter than content */
9195
overflow-y: auto;
9296
overflow-x: hidden;
@@ -102,13 +106,21 @@ button:focus, .navbar-dark .navbar-toggler:focus {
102106
}
103107
@media screen and (max-width: 991px) {
104108
.sidebar {
109+
position: fixed;
110+
top: 3.5em;
111+
height: calc(100% - 3.5rem);
105112
left: -100%;
106113
transition: 0.25s left ease-in-out;
107114
}
108115
.sidebar.show {
109116
left: 0;
110117
}
111118
}
119+
@media (min-width: 992px) {
120+
.sidebar {
121+
flex: 0 0 auto;
122+
}
123+
}
112124

113125
.contents {
114126
padding: 0.5em 0 0.5em 0.5em;
@@ -139,10 +151,13 @@ button:focus, .navbar-dark .navbar-toggler:focus {
139151
*/
140152

141153
.main {
154+
max-width: 100%;
142155
padding: 1.3em;
143156
}
144157
@media (min-width: 992px) {
145158
.main {
159+
flex: 1 1 auto;
160+
overflow: auto;
146161
padding-right: 2em;
147162
padding-left: 2em;
148163
}
@@ -221,12 +236,6 @@ h3, h4, h2 time {
221236
font-weight: 400;
222237
}
223238

224-
.main section {
225-
/* Offset the anchor so that clicking on the sidebar links don’t hide the heading under the header bar */
226-
padding-top: 2.3rem;
227-
margin-top: -2.3rem;
228-
}
229-
230239
@media (min-width: 1200px) {
231240
.main > header, .main section > h2, .main section > h3, .main section > h4, .main section > p, .main section > blockquote, .main section > ul, .main section > table {
232241
max-width: 80%;
@@ -246,7 +255,7 @@ code {
246255

247256

248257
/*
249-
* Code examples
258+
* Chrome around code examples; see code.css for the styling of the code blocks themselves
250259
*/
251260

252261
textarea {
@@ -281,31 +290,7 @@ textarea {
281290

282291
.play-button {
283292
height: 1em;
284-
}
285-
286-
.CodeMirror pre, pre.placeholder-code {
287-
line-height: 1.4em;
288-
}
289-
290-
.CodeMirror,
291-
.placeholder-code {
292-
/* https://codemirror.net/demo/resize.html */
293-
height: auto;
294-
background: transparent;
295-
font-family: 'Roboto Mono';
296-
font-weight: 400;
297-
line-height: 1.25;
298-
font-size: 0.9em;
299-
}
300-
@media (min-width: 768px) {
301-
.CodeMirror,
302-
.placeholder-code {
303-
font-size: 1em;
304-
}
305-
}
306-
307-
.CodeMirror-code:focus {
308-
outline: none;
293+
width: 1em;
309294
}
310295

311296
.javascript-output-column .CodeMirror-cursor {
@@ -324,6 +309,8 @@ textarea {
324309
right: 0;
325310
opacity: 0;
326311
transition: opacity 0.15s ease-in-out;
312+
z-index: -1001;
313+
background-color: #2f2625;
327314
}
328315
.try-coffeescript.show {
329316
opacity: 1;

‎documentation/site/icon.svg‎

Lines changed: 1 addition & 1 deletion
Loading

‎documentation/site/logo.svg‎

Lines changed: 1 addition & 1 deletion
Loading

0 commit comments

Comments
 (0)