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
jashkenas · Apr 27, 2018 · 776e7e5 · 776e7e5
1 parent 871079b
commit 776e7e5
Show file tree

Hide file tree

Showing 11 changed files with 386 additions and 291 deletions.
diff --git a/docs/v2/index.html b/docs/v2/index.html
diff --git a/documentation/site/body.html b/documentation/site/body.html
@@ -3,11 +3,11 @@
 <%= include('try.html') %>
 
 <div class="container-fluid" id="top">
-  <div class="row flex-nowrap">
-    <nav class="sidebar col-lg-3 bg-ribbed-light">
+  <div class="row flex-nowrap main-row">
+    <nav class="sidebar bg-ribbed-light">
       <%= include('sidebar.html') %>
     </nav>
-    <main class="main col-lg-9 ml-auto">
+    <main class="main">
       <header class="d-none d-lg-block">
         <p class="title-logo">
           <%= include('logo.svg') %>

diff --git a/documentation/site/code.css b/documentation/site/code.css
@@ -1,7 +1,15 @@
-/* Adapted from https://github.com/FarhadG/code-mirror-themes/blob/master/themes/twilight.css */
+/* 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 */
+
+/* CodeMirror general styling */
 
 .CodeMirror,
 .placeholder-code {
+  /* https://codemirror.net/demo/resize.html */
+  height: auto;
+  background: transparent;
+  font-family: 'Roboto Mono';
+  font-weight: 400;
+  line-height: 1.25;
   letter-spacing: 0.3px;
   color: #f8f8f8;
   /* 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 @@
 @media (min-width: 768px) {
   .CodeMirror,
   .placeholder-code {
-    font-size: 90%; /* Matching Bootstrap’s font size for code, which calculates to 14.4px */
+    font-size: 87.5%; /* Matching Bootstrap’s font size for code, which calculates to 14.4px */
   }
 }
 .CodeMirror-lines {
@@ -21,6 +29,13 @@
   margin-bottom: 1.37em;
   white-space: pre-wrap;
 }
+.CodeMirror pre,
+pre.placeholder-code {
+  line-height: 1.4em;
+}
+.CodeMirror-code:focus {
+  outline: none;
+}
 div.CodeMirror-cursor {
   border-left: 3px solid #f8f8f8;
 }
@@ -30,27 +45,18 @@ div.CodeMirror-cursor {
 .CodeMirror-selected {
   background: #ddf0ff33;
 }
-.cm-comment,
-.placeholder-code .comment {
-  font-style: italic;
-  color: #5f5a60;
-}
+
+/* Syntax highlighting */
+
 .cm-keyword,
 .placeholder-code .keyword {
   color: #cda869;
 }
-.cm-string,
-.placeholder-code .string {
-  color: #8f9d6a;
-}
-.cm-property,
-.placeholder-code .attribute {
-  color: #dad085;
-}
 .cm-atom {
   color: #dad085;
 }
 .cm-number,
+.cm-meta,
 .placeholder-code .number,
 .placeholder-code .built_in,
 .placeholder-code .builtin-name,
@@ -61,6 +67,18 @@ div.CodeMirror-cursor {
 .placeholder-code .link {
   color: #dad085;
 }
+.cm-def {
+  color: #f8f8f8;
+}
+span.cm-variable-2,
+span.cm-tag {
+  color: #f8f8f8;
+}
+span.cm-variable-3,
+span.cm-def,
+span.cm-type {
+  color: #f8f8f8;
+}
 .cm-operator,
 .placeholder-code .punctuation,
 .placeholder-code .symbol,
@@ -69,9 +87,50 @@ div.CodeMirror-cursor {
 .placeholder-code .operator {
   color: #cda869;
 }
+.cm-comment,
+.placeholder-code .comment {
+  font-style: italic;
+  color: #5f5a60;
+}
+.cm-string,
+.cm-string-2,
+.placeholder-code .string {
+  color: #8f9d6a;
+}
+.cm-property,
+.placeholder-code .attribute {
+  color: #dad085;
+}
+.cm-builtin {
+  color: #cda869;
+}
+.cm-tag {
+  color: #997643;
+}
+.cm-attribute {
+  color: #d6bb6d;
+}
+.cm-header {
+  color: #FF6400;
+}
+.cm-hr {
+  color: #AEAEAE;
+}
+.cm-link {
+  color: #ad9361;
+  font-style: italic;
+  text-decoration: none;
+}
+.cm-error {
+  border-bottom: 1px solid rgba(142, 22, 22, 0.67);
+}
 
 /* Uneditable code blocks are inverted, so use darker versions of the above */
 
+.uneditable-code-block code {
+  padding: 0;
+}
+
 .uneditable-code-block .comment {
   font-style: italic;
   color: #837B85;

diff --git a/documentation/site/docs.coffee b/documentation/site/docs.coffee
@@ -1,6 +1,18 @@
 unless window.location.origin # Polyfill `location.origin` for IE < 11
   window.location.origin = "#{window.location.protocol}//#{window.location.hostname}"
 
+
+# Initialize Google Analytics
+window.GA_TRACKING_ID = 'UA-106156830-1'
+window.dataLayer ?= []
+window.gtag = ->
+  window.dataLayer.push arguments
+  return
+window.gtag 'js', new Date()
+window.gtag 'config', window.GA_TRACKING_ID
+
+
+# Initialize the CoffeeScript docs interactions
 $(document).ready ->
   # Mobile navigation
   toggleSidebar = ->
@@ -21,14 +33,14 @@ $(document).ready ->
 
   # Initialize Scrollspy for sidebar navigation; https://getbootstrap.com/docs/4.0/components/scrollspy/
   # See also http://www.codingeverything.com/2014/02/BootstrapDocsSideBar.html and http://jsfiddle.net/KyleMit/v6zhz/
-  $('body').scrollspy
+  $('.main').scrollspy
     target: '#contents'
     offset: Math.round $('main').css('padding-top').replace('px', '')
 
   initializeScrollspyFromHash = (hash) ->
     $("#contents a.active[href!='#{hash}']").removeClass 'show'
 
-  $(window).on 'activate.bs.scrollspy', (event, target) -> # Why `window`? https://github.com/twbs/bootstrap/issues/20086
+  $('.main').on 'activate.bs.scrollspy', (event, target) ->
     # We only want one active link in the nav
     $("#contents a.active[href!='#{target.relatedTarget}']").removeClass 'show'
     $target = $("#contents a[href='#{target.relatedTarget}']")
@@ -165,6 +177,11 @@ $(document).ready ->
     toggleTry yes
   $('[data-close="try"]').click closeTry
 
+  $('[data-action="scroll-to-top"]').click (event) ->
+    return if $('#try').hasClass('show')
+    $('.main')[0].scrollTop = 0
+    setTimeout clearHash, 10
+
   clearHash = ->
     window.history.replaceState {}, document.title, window.location.pathname
 

diff --git a/documentation/site/docs.css b/documentation/site/docs.css
@@ -79,14 +79,18 @@ button:focus, .navbar-dark .navbar-toggler:focus {
 }
 
 
+/*
+ * Layout; based on https://codepen.io/Sphinxxxx/pen/WjwbEO
+ */
+.main-row {
+  height: calc(100vh - 3.5rem);
+}
+
 /*
  * Sidebar
  */
 
 .sidebar {
-  position: fixed;
-  top: 3.5em;
-  height: calc(100% - 3.5rem);
   /* Scrollable contents if viewport is shorter than content */
   overflow-y: auto;
   overflow-x: hidden;
@@ -102,13 +106,21 @@ button:focus, .navbar-dark .navbar-toggler:focus {
 }
 @media screen and (max-width: 991px) {
   .sidebar {
+    position: fixed;
+    top: 3.5em;
+    height: calc(100% - 3.5rem);
     left: -100%;
     transition: 0.25s left ease-in-out;
   }
   .sidebar.show {
     left: 0;
   }
 }
+@media (min-width: 992px) {
+  .sidebar {
+    flex: 0 0 auto;
+  }
+}
 
 .contents {
   padding: 0.5em 0 0.5em 0.5em;
@@ -139,10 +151,13 @@ button:focus, .navbar-dark .navbar-toggler:focus {
  */
 
 .main {
+  max-width: 100%;
   padding: 1.3em;
 }
 @media (min-width: 992px) {
   .main {
+    flex: 1 1 auto;
+    overflow: auto;
     padding-right: 2em;
     padding-left: 2em;
   }
@@ -221,12 +236,6 @@ h3, h4, h2 time {
   font-weight: 400;
 }
 
-.main section {
-  /* Offset the anchor so that clicking on the sidebar links don’t hide the heading under the header bar */
-  padding-top: 2.3rem;
-  margin-top: -2.3rem;
-}
-
 @media (min-width: 1200px) {
   .main > header, .main section > h2, .main section > h3, .main section > h4, .main section > p, .main section > blockquote, .main section > ul, .main section > table {
     max-width: 80%;
@@ -246,7 +255,7 @@ code {
 
 
 /*
- * Code examples
+ * Chrome around code examples; see code.css for the styling of the code blocks themselves
  */
 
 textarea {
@@ -281,31 +290,7 @@ textarea {
 
 .play-button {
   height: 1em;
-}
-
-.CodeMirror pre, pre.placeholder-code {
-  line-height: 1.4em;
-}
-
-.CodeMirror,
-.placeholder-code {
-  /* https://codemirror.net/demo/resize.html */
-  height: auto;
-  background: transparent;
-  font-family: 'Roboto Mono';
-  font-weight: 400;
-  line-height: 1.25;
-  font-size: 0.9em;
-}
-@media (min-width: 768px) {
-  .CodeMirror,
-  .placeholder-code {
-    font-size: 1em;
-  }
-}
-
-.CodeMirror-code:focus {
-  outline: none;
+  width: 1em;
 }
 
 .javascript-output-column .CodeMirror-cursor {
@@ -324,6 +309,8 @@ textarea {
   right: 0;
   opacity: 0;
   transition: opacity 0.15s ease-in-out;
+  z-index: -1001;
+  background-color: #2f2625;
 }
 .try-coffeescript.show {
   opacity: 1;

diff --git a/documentation/site/icon.svg b/documentation/site/icon.svg
diff --git a/documentation/site/logo.svg b/documentation/site/logo.svg