Merge pull request #90 from tripit/dev

Version 1.0

Author: Tariq Islam

CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## Version 1.0
+
+*July 2, 2014*
+
+[View Issues](https://github.com/tripit/slate/issues?milestone=1&state=closed)
+
+**Features:**
+
+- Responsive designs for phones and tablets
+- Started tagging versions
+
+**Fixes:**
+
+- Fixed 'unrecognized expression' error
+- Fixed #undefined hash bug
+- Fixed bug where the current language tab would be unselected
+- Fixed bug where tocify wouldn't highlight the current section while searching
+- Fixed bug where ids of header tags would have special characters that caused problems
+- Updated layout so that pages with disabled search wouldn't load search.js
+- Cleaned up Javascript

README.md

@@ -3,18 +3,18 @@ Slate
 
 [![Build Status](https://travis-ci.org/tripit/slate.svg?branch=master)](https://travis-ci.org/tripit/slate) [![Dependency Status](https://gemnasium.com/tripit/slate.png)](https://gemnasium.com/tripit/slate)
 
-Slate helps you create beautiful single-page API documentation. Think of it as an intelligent, modern documentation template for your API.
+Slate helps you create beautiful API documentation. Think of it as an intelligent, responsive documentation template for your API.
 
-<img src="https://dl.dropboxusercontent.com/u/95847291/github%20images/slate/slate_screenshot.png" width=700 alt="Screenshot of Example Documentation created with Slate">
+<img src="https://dl.dropboxusercontent.com/u/95847291/github%20images/slate/slate_screenshot_new.png" width=700 alt="Screenshot of Example Documentation created with Slate">
 
 *The example above was created with Slate. Check it out at [tripit.github.io/slate](http://tripit.github.io/slate).*
 
 Features
 ------------
 
-* **Clean, intuitive design** — with Slate, the description of your API is on the left side of your documentation, and all the code examples are on the right side. Inspired by [Stripe's](https://stripe.com/docs/api) and [Paypal's](https://developer.paypal.com/webapps/developer/docs/api/) API docs. In addition to the design you see on screen, Slate comes with a print stylesheet, so your docs look great on paper.
+* **Clean, intuitive design** — with Slate, the description of your API is on the left side of your documentation, and all the code examples are on the right side. Inspired by [Stripe's](https://stripe.com/docs/api) and [Paypal's](https://developer.paypal.com/webapps/developer/docs/api/) API docs. Slate is responsive, so it looks great on tablets, phones, and even print.
 
-* **Everything on a single page** — gone are the days where your users had to search through a million pages to find what they wanted. Slate puts the entire documentation on a single page. We haven't sacrificed linkability, though. As you scroll, your browser's hash will update to the nearest header, so it's insanely easy to link to a particular point in the documentation.
+* **Everything on a single page** — gone are the days where your users had to search through a million pages to find what they wanted. Slate puts the entire documentation on a single page. We haven't sacrificed linkability, though. As you scroll, your browser's hash will update to the nearest header, so linking to a particular point in the documentation is still natural and easy.
 
 * **Slate is just Markdown** — when you write docs with Slate, you're just writing Markdown, which makes it simple to edit and understand. Everything is written in Markdown — even the code samples are just Markdown code blocks!
 
@@ -55,6 +55,8 @@ Now that Slate is all set up your machine, you'll probably want to learn more ab
 Examples of Slate in the Wild
 ---------------------------------
 
+* [Travis-CI's API docs](http://docs.travis-ci.com/api/)
+* [Mozilla's localForage docs](http://mozilla.github.io/localForage/)
 * [Orchestrate.io API docs](https://docs.orchestrate.io/)
 * [ChaiOne Gameplan API docs](http://chaione.github.io/gameplanb2b/#introduction)
 * [Drcaban's Build a Quine tutorial](http://drcabana.github.io/build-a-quine/#introduction)
@@ -69,18 +71,22 @@ Need Help? Found a bug?
 Just [submit a issue](https://github.com/tripit/slate/issues) to the Slate Github if you need any help. And, of course, feel free to submit pull requests with bug fixes or changes.
 
 
+Contributors
+--------------------
+
+Slate was built by [Robert Lord](http://lord.io) while at [TripIt](http://tripit.com).
+
+Thanks to the following people who have submitted major pull requests:
+
+- [@chrissrogers](https://github.com/chrissrogers)
+- [@bootstraponline](https://github.com/bootstraponline)
+
+Also, thanks to [Sauce Labs](http://saucelabs.com) for helping sponsor the project.
+
 Special Thanks
 --------------------
 - [Middleman](https://github.com/middleman/middleman)
 - [jquery.tocify.js](https://github.com/gfranko/jquery.tocify.js)
 - [middleman-syntax](https://github.com/middleman/middleman-syntax)
 - [middleman-gh-pages](https://github.com/neo/middleman-gh-pages)
 - [Font Awesome](http://fortawesome.github.io/Font-Awesome/)
-
-Contributors
---------------------
-
-Thanks to the following people who have submitted pull requests:
-
-- [@chrissrogers](https://github.com/chrissrogers)
-- [@bootstraponline](https://github.com/bootstraponline)

config.rb

@@ -1,3 +1,5 @@
+require './lib/redcarpet_header_fix'
+
 set :css_dir, 'stylesheets'
 
 set :js_dir, 'javascripts'
@@ -34,3 +36,4 @@
   # Or use a different image path
   # set :http_prefix, "/Content/images/"
 end
+

lib/redcarpet_header_fix.rb

@@ -0,0 +1,9 @@
+module RedcarpetHeaderFix
+  def header(text, level, id)
+    clean_id = id.gsub(/[\.]/, '-').gsub(/[^a-zA-Z0-9\-_]/, '')
+    "<h#{level} id='#{clean_id}'>#{text}</h1>"
+  end
+end
+
+require 'middleman-core/renderers/redcarpet'
+Middleman::Renderers::MiddlemanRedcarpetHTML.send :include, RedcarpetHeaderFix

source/images/navbar.png

@@ -0,0 +1,4 @@
+//= require_tree ./lib
+//= require_tree ./app
+//= stub ./app/search.js
+//= stub ./lib/lunr.js

source/javascripts/all_nosearch.js

@@ -21,9 +21,10 @@ under the License.
 
   function activateLanguage(language) {
     if (!language) return;
+    if (language === "") return;
 
-    $("#lang-selector a").removeClass('active');
-    $("#lang-selector a[data-language-name='" + language + "']").addClass('active');
+    $(".lang-selector a").removeClass('active');
+    $(".lang-selector a[data-language-name='" + language + "']").addClass('active');
     for (var i=0; i < languages.length; i++) {
       $(".highlight." + languages[i]).hide();
     }
@@ -41,6 +42,9 @@ under the License.
       hash = hash.replace(/^#+/, '');
     }
     history.pushState({}, '', '?' + language + '#' + hash);
+
+    // save language as next default
+    localStorage.setItem("language", language);
   }
 
   function setupLanguages(l) {
@@ -53,7 +57,6 @@ under the License.
       // the language is in the URL, so use that language!
       activateLanguage(location.search.substr(1));
 
-      // set this language as the default for next time, if the URL has no language
       localStorage.setItem("language", location.search.substr(1));
     } else if ((defaultLanguage !== null) && (jQuery.inArray(defaultLanguage, languages) != -1)) {
       // the language was the last selected one saved in localstorage, so use that language!
@@ -66,7 +69,7 @@ under the License.
 
   // if we click on a language tab, activate that language
   $(function() {
-    $("#lang-selector a").on("click", function() {
+    $(".lang-selector a").on("click", function() {
       var language = $(this).data("language-name");
       pushURL(language);
       activateLanguage(language);

source/javascripts/app/lang.js

@@ -1,10 +1,10 @@
 (function (global) {
 
   var $global = $(global);
-  var content, darkBox, searchInfo;
+  var content, darkBox, searchResults;
   var highlightOpts = { element: 'span', className: 'search-highlight' };
 
-  var index = new lunr.Index;
+  var index = new lunr.Index();
 
   index.ref('id');
   index.field('title', { boost: 10 });
@@ -14,15 +14,10 @@
   $(populate);
   $(bind);
 
-  function populate () {
-    $('h1').each(function () {
+  function populate() {
+    $('h1, h2').each(function() {
       var title = $(this);
-      var body = title.nextUntil('h1');
-      var wrapper = $('<section id="section-' + title.prop('id') + '"></section>');
-
-      title.after(wrapper.append(body));
-      wrapper.prepend(title);
-
+      var body = title.nextUntil('h1, h2');
       index.add({
         id: title.prop('id'),
         title: title.text(),
@@ -31,99 +26,46 @@
     });
   }
 
-  function bind () {
+  function bind() {
     content = $('.content');
     darkBox = $('.dark-box');
-    searchInfo = $('.search-info');
-
-    $('#input-search')
-      .on('keyup', search)
-      .on('focus', active)
-      .on('blur', inactive);
-  }
-
-  function refToHeader (itemRef) {
-    return $('.tocify-item[data-unique=' + itemRef + ']').closest('.tocify-header');
-  }
+    searchResults = $('.search-results');
 
-  function sortDescending (obj2, obj1) {
-    var s1 = parseInt(obj1.id.replace(/[^\d]/g, ''), 10);
-    var s2 = parseInt(obj2.id.replace(/[^\d]/g, ''), 10);
-    return s1 === s2 ? 0 : s1 < s2 ? -1 : 1;
+    $('#input-search').on('keyup', search);
   }
 
-  function resetHeaderLocations () {
-    var headers = $(".tocify-header").sort(sortDescending);
-    $.each(headers, function (index, item) {
-      $(item).insertBefore($("#toc ul:first-child"));
-    });
-  }
-
-  function search (event) {
-    var sections = $('section, #toc .tocify-header');
-
-    searchInfo.hide();
+  function search(event) {
     unhighlight();
+    searchResults.addClass('visible');
 
     // ESC clears the field
     if (event.keyCode === 27) this.value = '';
 
     if (this.value) {
-      sections.hide();
-      // results are sorted by score in descending order
-      var results = index.search(this.value);
+      var results = index.search(this.value).filter(function(r) {
+        return r.score > 0.0001;
+      });
 
       if (results.length) {
-        resetHeaderLocations();
-        var lastRef;
-        $.each(results, function (index, item) {
-          if (item.score <= 0.0001) return; // remove low-score results
-          var itemRef = item.ref;
-          $('#section-' + itemRef).show();
-          // headers must be repositioned in the DOM
-          var closestHeader = refToHeader(itemRef);
-          if (lastRef) {
-            refToHeader(lastRef).insertBefore(closestHeader);
-          }
-          closestHeader.show();
-          lastRef = itemRef;
+        searchResults.empty();
+        $.each(results, function (index, result) {
+          searchResults.append("<li><a href='#" + result.ref + "'>" + $('#'+result.ref).text() + "</a></li>");
         });
-
-        // position first element. it wasn't positioned above if len > 1
-        if (results.length > 1) {
-          var firstRef = results[0].ref;
-          var secondRef = results[1].ref
-          refToHeader(firstRef).insertBefore(refToHeader(secondRef));
-        }
-
         highlight.call(this);
       } else {
-        sections.show();
-        searchInfo.text('No Results Found for "' + this.value + '"').show();
+        searchResults.html('<li>No Results Found for "' + this.value + '"</li>');
       }
     } else {
-      sections.show();
+      unhighlight();
+      searchResults.removeClass('visible');
     }
-
-    // HACK trigger tocify height recalculation
-    $global.triggerHandler('scroll.tocify');
-    $global.triggerHandler('resize');
-  }
-
-  function active () {
-    search.call(this, {});
-  }
-
-  function inactive () {
-    unhighlight();
-    searchInfo.hide();
   }
 
-  function highlight () {
+  function highlight() {
     if (this.value) content.highlight(this.value, highlightOpts);
   }
 
-  function unhighlight () {
+  function unhighlight() {
     content.unhighlight(highlightOpts);
   }
 

source/javascripts/app/search.js

@@ -1,14 +1,12 @@
 (function (global) {
 
-  var toc;
+  var closeToc = function() {
+    $(".tocify-wrapper").removeClass('open');
+    $("#nav-button").removeClass('open');
+  };
 
-  global.toc = toc;
-
-  $(toc);
-  $(animate);
-
-  function toc () {
-    toc = $("#toc").tocify({
+  var makeToc = function() {
+    global.toc = $("#toc").tocify({
       selectors: 'h1, h2',
       extendPage: false,
       theme: 'none',
@@ -17,13 +15,22 @@
       hideEffectSpeed: 180,
       ignoreSelector: '.toc-ignore',
       highlightOffset: 60,
-      scrollTo: -2,
+      scrollTo: -1,
       scrollHistory: true,
       hashGenerator: function (text, element) {
         return element.prop('id');
       }
     }).data('toc-tocify');
-  }
+
+    $("#nav-button").click(function() {
+      $(".tocify-wrapper").toggleClass('open');
+      $("#nav-button").toggleClass('open');
+      return false;
+    });
+
+    $(".page-wrapper").click(closeToc);
+    $(".tocify-item").click(closeToc);
+  };
 
   // Hack to make already open sections to start opened,
   // instead of displaying an ugly animation
@@ -33,5 +40,8 @@
     }, 50);
   }
 
+  $(makeToc);
+  $(animate);
+
 })(window);