Merge pull request #537 from parkr/docs-update

WIP: Spike out the documentation

.travis.yml

@@ -0,0 +1,4 @@
+install: gem install github-pages
+script: jekyll build --trace
+sudo: false
+rvm: 2.1

_config.yml

@@ -1,14 +1,10 @@
-# Site settings
-title: Your awesome title
-email: your-email@domain.com
-description: > # this means to ignore newlines until "baseurl:"
-  Write an awesome description for your new site here. You can edit this
-  line in _config.yml. It will appear in your document head meta (for
-  Google search results) and in your feed.xml site description.
-baseurl: "" # the subpath of your site, e.g. /blog/
-url: "http://yourdomain.com" # the base hostname & protocol for your site
-twitter_username: jekyllrb
-github_username:  jekyll
-
 # Build settings
+baseurl: "" # the subpath of your site, e.g. /blog/
+url: "http://liquidmarkup.org" # the base hostname & protocol for your site
 markdown: kramdown
+permalink: /:year/:month/:day/:basename:output_ext
+collections:
+  - filters
+exclude:
+  - README.md
+  - CNAME

_data/site.yml

@@ -0,0 +1,6 @@
+# Site settings
+title: Liquid Templating Engine
+description: > # this means to ignore newlines until "baseurl:"
+  Liquid is a template language and accompanying rendering engine.
+  It is built for security, so is perfect for rendering custom
+  templates from your users.

_filters/append.md

@@ -0,0 +1,22 @@
+---
+title: append
+---
+
+`append` concatenates two strings and returns the concatenated value.
+
+{% highlight liquid %}
+{% raw %}
+{{ "/my/fancy/url" | append:".html" }}
+{% endraw %}
+# => "/my/fancy/url.html"
+{% endhighlight %}
+
+It can also be used with variables:
+
+{% highlight liquid %}
+{% raw %}
+{% assign filename = "/index.html" %}
+{{ product.url | append:filename }}
+{% endraw %}
+# => "#{product.url}/index.html"
+{% endhighlight %}

_filters/capitalize.md

@@ -0,0 +1,12 @@
+---
+title: capitalize
+---
+
+`capitalize` ensures the first character of your string is capitalized.
+
+| Input                                                      | Output           |
+|-----------------------------------------------------------:|:-----------------|
+| {% raw %}`{{ "title" | capitalize }}`         {% endraw %} | "Title"          |
+| {% raw %}`{{ "my great title" | capitalize }}`{% endraw %} | "My great title" |
+
+It only capitalizes the first character, so subsequent words will not be capitalized as well.

_filters/ceil.md

@@ -0,0 +1,14 @@
+---
+title: ceil
+---
+
+`ceil` rounds the input up to the nearest whole number.
+
+| Input                                      | Output |
+|-------------------------------------------:|:-------|
+| {% raw %}`{{ 1.2 | ceil }}`   {% endraw %} | 2      |
+| {% raw %}`{{ 1.7 | ceil }}`   {% endraw %} | 2      |
+| {% raw %}`{{ 2.0 | ceil }}`   {% endraw %} | 2      |
+| {% raw %}`{{ "18.3" | ceil }}`{% endraw %} | 19     |
+
+It will attempt to cast any input to a number.

_filters/date.md

@@ -0,0 +1,12 @@
+---
+title: date
+---
+
+`date` converts a timestamp into another date format.
+
+| Input                                                                     | Output               |
+|--------------------------------------------------------------------------:|:---------------------|
+| {% raw %}`{{ article.published_at | date: "%a, %b %d, %y" }}`{% endraw %} | Tue, Apr 22, 14      |
+| {% raw %}`{{ article.published_at | date: "%Y" }}`{% endraw %}            | 2014                 |
+
+The format for this syntax is the same as [`strftime`](http://strftime.net/).

_filters/default.md

@@ -0,0 +1,22 @@
+---
+title: default
+---
+
+`default` offers a means of having a fall-back value in case your value doesn't exist.
+
+{% highlight liquid %}
+{% raw %}
+{{ product_price | default:2.99 }}
+// => outputs "2.99"
+
+{% assign product_price = 4.99 %}
+{{ product_price | default:2.99 }}
+// => outputs "4.99"
+
+{% assign product_price = "" %}
+{{ product_price | default:2.99 }}
+// => outputs "2.99"
+{% endraw %}
+{% endhighlight %}
+
+`default` will use its substitute if the left side is `nil`, `false`, or empty.

_filters/divided_by.md

@@ -0,0 +1,12 @@
+---
+title: divided_by
+---
+
+This filter divides its input by its parameter.
+
+| Code                                              | Output |
+|--------------------------------------------------:|:-------|
+| {% raw %}`{{ 4 | divided_by: 2 }}`   {% endraw %} | 2      |
+| {% raw %}`{{ "16" | divided_by: 4 }}`{% endraw %} | 4      |
+
+It uses `to_number`, which converts to a decimal value unless already a numeric.

_filters/downcase.md

@@ -0,0 +1,11 @@
+---
+title: downcase
+---
+
+This filter makes the entire input string the lower case version of each character within.
+
+| Code                                                   | Output           |
+|-------------------------------------------------------:|:-----------------|
+| {% raw %}`{{ "Peter Parker" | downcase }}`{% endraw %} | `"peter parker"` |
+
+It doesn't modify strings which are already entirely lowercase. It works with anything that has a `#to_s` method.

_filters/escape.md

@@ -0,0 +1,12 @@
+---
+title: escape
+---
+
+Escapes a string by replacing characters with escape sequences (so that the string can be used in a URI).
+
+| Code                                                   | Output             |
+|-------------------------------------------------------:|:-------------------|
+| {% raw %}`{{ "Need tips? Ask a friend!" | escape }}`{% endraw %}     | `"Need%20tips%3F%Ask%20a%20friend%21"` |
+| {% raw %}`{{ "Nope" | escape }}`{% endraw %}           | `"Nope"` |
+
+It doesn't modify strings that have nothing to escape.

_filters/escape_once.md

@@ -0,0 +1,13 @@
+---
+title: escape_once
+---
+
+Escapes a string without affecting existing escaped entities.
+
+| Code                                                   | Output             |
+|-------------------------------------------------------:|:-------------------|
+| {% raw %}`{{ "1 < 2 & 3" | escape_once }}`{% endraw %}     | `"1 < 2 & 3"` |
+| {% raw %}`{{ "<< Accept & Checkout" | escape_once }}`{% endraw %}     | `"<< Accept & Checkout"` |
+| {% raw %}`{{ "Nope" | escape_once }}`{% endraw %}           | `"Nope"` |
+
+It doesn't modify strings that have nothing to escape.

_filters/first.md

@@ -0,0 +1,11 @@
+---
+title: first
+---
+
+Return the first element of an array.
+
+| Code                                                   | Output             |
+|-------------------------------------------------------:|:-------------------|
+| {% raw %}`{{ product.tags | first }}`{% endraw %}     | `"sale"` |
+
+In the sample above, assume that `product.tags` resolves to: `["sale", "mens", "womens", "awesome"]`.

_filters/floor.md

@@ -0,0 +1,14 @@
+---
+title: floor
+---
+
+`floor` rounds the input down to the nearest whole number.
+
+| Input                                      | Output |
+|-------------------------------------------:|:-------|
+| {% raw %}`{{ 1.2 | floor }}`   {% endraw %} | 1      |
+| {% raw %}`{{ 1.7 | floor }}`   {% endraw %} | 1      |
+| {% raw %}`{{ 2.0 | floor }}`   {% endraw %} | 2      |
+| {% raw %}`{{ "18.3" | floor }}`{% endraw %} | 18     |
+
+It will attempt to cast any input to a number.

_filters/h.md

@@ -0,0 +1,3 @@
+---
+title: h
+---

_filters/join.md

@@ -0,0 +1,11 @@
+---
+title: join
+---
+
+`join` joins the elements of an array, using the character you provide.
+
+| Code                                                   | Output             |
+|-------------------------------------------------------:|:-------------------|
+| {% raw %}`{{ product.tags | join: ', ' }}`{% endraw %}     | `"sale, mens, womens, awesome` |
+
+In the sample above, assume that `product.tags` resolves to: `["sale", "mens", "womens", "awesome"]`.

_filters/last.md

@@ -0,0 +1,11 @@
+---
+title: last
+---
+
+Return the last element of an array.
+
+| Code                                                   | Output             |
+|-------------------------------------------------------:|:-------------------|
+| {% raw %}`{{ product.tags | last }}`{% endraw %}     | `"awesome"` |
+
+In the sample above, assume that `product.tags` resolves to: `["sale", "mens", "womens", "awesome"]`.

_filters/lstrip.md

@@ -0,0 +1,9 @@
+---
+title: lstrip
+---
+
+Strips all whitespace (tabs, spaces, and newlines) from the left side of a string.
+
+| Code                                                   | Output             |
+|-------------------------------------------------------:|:-------------------|
+| {% raw %}`{{ '   too many spaces   ' | lstrip }}`{% endraw %}     | `"too many spaces   "` |

_filters/map.md

@@ -0,0 +1,11 @@
+---
+title: map
+---
+
+Collects an array of properties from a hash.
+
+| Code                                                   | Output             |
+|-------------------------------------------------------:|:-------------------|
+| {% raw %}`{{ product | map: 'tag' }}`{% endraw %}     | `["sale", "mens", "womens", "awesome"]` |
+
+In the sample above, assume that `product` resolves to: `[{ tags: "sale"}, { tags: "mens"}, { tags: "womens"}, { tags: "awesome"}]`.

_filters/minus.md

@@ -0,0 +1,9 @@
+---
+title: minus
+---
+
+Subtracts two numbers.
+
+| Code                                                   | Output             |
+|-------------------------------------------------------:|:-------------------|
+| {% raw %}`{{ 100 | minus: 10 }}`{% endraw %}     | `90` |

_filters/modulo.md

@@ -0,0 +1,9 @@
+---
+title: modulo
+---
+
+Performs a modulo operation (eg., fetches the remainder).
+
+| Code                                                   | Output             |
+|-------------------------------------------------------:|:-------------------|
+| {% raw %}`{{ 2 | modulo: 2 }}`{% endraw %}     | `1` |

_filters/newline_to_br.md

@@ -0,0 +1,9 @@
+---
+title: newline_to_br
+---
+
+Replace every newline (`n`) with an HTML break (`<br>`).
+
+| Code                                                   | Output             |
+|-------------------------------------------------------:|:-------------------|
+| {% raw %}`{{ "hello\nthere" | newline_to_br }}`{% endraw %}     | `hello<br/>there` |

_filters/plus.md

@@ -0,0 +1,9 @@
+---
+title: plus
+---
+
+Adds two numbers.
+
+| Code                                                   | Output             |
+|-------------------------------------------------------:|:-------------------|
+| {% raw %}`{{ 100 | plus: 10 }}`{% endraw %}     | `110` |

_filters/prepend.md

@@ -0,0 +1,9 @@
+---
+title: prepend
+---
+
+Prepends a string onto another.
+
+| Code                                                   | Output             |
+|-------------------------------------------------------:|:-------------------|
+| {% raw %}`{{ 'world' | prepend: 'hello ' }}`{% endraw %}     | `hello world` |

_filters/remove.md

@@ -0,0 +1,9 @@
+---
+title: remove
+---
+
+Removes every occurrence of a given string.
+
+| Code                                                   | Output             |
+|-------------------------------------------------------:|:-------------------|
+| {% raw %}`{{ 'hello, hello world' | remove: 'hello' }}`{% endraw %}     | `,  world` |

_filters/remove_first.md

@@ -0,0 +1,9 @@
+---
+title: remove_first
+---
+
+Removes the first occurrence of a given string.
+
+| Code                                                   | Output             |
+|-------------------------------------------------------:|:-------------------|
+| {% raw %}`{{ 'hello, hello world' | remove_first: 'hello' }}`{% endraw %}     | `, hello world` |

_filters/replace.md

@@ -0,0 +1,9 @@
+---
+title: replace
+---
+
+Replaces every occurrence of a given string.
+
+| Code                                                   | Output             |
+|-------------------------------------------------------:|:-------------------|
+| {% raw %}`{{ 'hello, hello world' | replace: 'hello', 'goodbye' }}`{% endraw %}     | `goodbye, goodbye world` |

_filters/replace_first.md

@@ -0,0 +1,9 @@
+---
+title: replace_first
+---
+
+Replaces the first occurrence of a given string.
+
+| Code                                                   | Output             |
+|-------------------------------------------------------:|:-------------------|
+| {% raw %}`{{ 'hello, hello world' | replace_first: 'hello', 'goodbye' }}`{% endraw %}     | `goodbye, hello world` |

_filters/reverse.md

@@ -0,0 +1,3 @@
+---
+title: reverse
+---

_filters/round.md

@@ -0,0 +1,3 @@
+---
+title: round
+---

_filters/rstrip.md

@@ -0,0 +1,9 @@
+---
+title: rstrip
+---
+
+Strips all whitespace (tabs, spaces, and newlines) from the right side of a string.
+
+| Code                                                   | Output             |
+|-------------------------------------------------------:|:-------------------|
+| {% raw %}`{{ '   too many spaces   ' | rstrip }}`{% endraw %}     | `"too many spaces   "` |

_filters/size.md

@@ -0,0 +1,3 @@
+---
+title: size
+---

_filters/slice.md

@@ -0,0 +1,3 @@
+---
+title: slice
+---

_filters/sort.md

@@ -0,0 +1,3 @@
+---
+title: sort
+---

_filters/split.md

@@ -0,0 +1,3 @@
+---
+title: split
+---

_filters/strip.md

@@ -0,0 +1,9 @@
+---
+title: strip
+---
+
+Strips all whitespace (tabs, spaces, and newlines) from a string.
+
+| Code                                                   | Output             |
+|-------------------------------------------------------:|:-------------------|
+| {% raw %}`{{ '   too many spaces   ' | strip }}`{% endraw %}     | `"too many spaces"` |

_filters/strip_html.md

@@ -0,0 +1,3 @@
+---
+title: strip_html
+---

_filters/strip_newlines.md

@@ -0,0 +1,3 @@
+---
+title: strip_newlines
+---

_filters/times.md

@@ -0,0 +1,3 @@
+---
+title: times
+---

_filters/truncate.md

@@ -0,0 +1,3 @@
+---
+title: truncate
+---

_filters/truncatewords.md

@@ -0,0 +1,3 @@
+---
+title: truncatewords
+---

_filters/uniq.md

@@ -0,0 +1,3 @@
+---
+title: uniq
+---

_filters/upcase.md

@@ -0,0 +1,3 @@
+---
+title: upcase
+---

_filters/url_encode.md

@@ -0,0 +1,3 @@
+---
+title: url_encode
+---

_includes/footer.html

@@ -2,13 +2,12 @@
 
   <div class="wrapper">
 
-    <h2 class="footer-heading">{{ site.title }}</h2>
+    <h2 class="footer-heading">{{ site.data.site.title }}</h2>
 
     <div class="footer-col-wrapper">
       <div class="footer-col  footer-col-1">
         <ul class="contact-list">
-          <li>{{ site.title }}</li>
-          <li><a href="mailto:{{ site.email }}">{{ site.email }}</a></li>
+          <li>{{ site.data.site.title }}</li>
         </ul>
       </div>
     </div>

_includes/head.html

@@ -3,8 +3,8 @@
   <meta http-equiv="X-UA-Compatible" content="IE=edge">
   <meta name="viewport" content="width=device-width, initial-scale=1">
 
-  <title>{% if page.title %}{{ page.title }}{% else %}{{ site.title }}{% endif %}</title>
-  <meta name="description" content="{% if page.excerpt %}{{ page.excerpt | strip_html | strip_newlines | truncate: 160 }}{% else %}{{ site.description }}{% endif %}">
+  <title>{% if page.title %}{{ page.title }} – {% endif %}{{ site.data.site.title }}</title>
+  <meta name="description" content="{% if page.excerpt %}{{ page.excerpt | strip_html | strip_newlines | truncate: 160 }}{% else %}{{ site.data.site.description }}{% endif %}">
 
   <link rel="stylesheet" href="{{ "/css/main.css" | prepend: site.baseurl }}">
   <link href='http://fonts.googleapis.com/css?family=Droid+Sans:400,700' rel='stylesheet' type='text/css'>

_layouts/default.html

@@ -8,15 +8,16 @@
       <h1 class="sidebar--logo"><a href="/">Liquid</a></h1>
       <nav class="sidebar--nav">
         <ul>
-          <li><a href="#">Nav Item 1</a>
+          {% for collection in site.collections %}
+          <li><a href="{{ collection[0] | prepend: "/" | prepend: site.baseurl | append: "/" }}">{{ collection[0] | capitalize }}</a>
             <ul>
-              <li><a href="#">Sub Nav Item 1</a></li>
-              <li><a href="#">Sub Nav Item 2</a></li>
-              <li><a href="#">Sub Nav Item 3 (Active)</a></li>
-              <li><a href="#">Sub Nav Item 4</a></li>
+              {% for doc in collection[1].docs %}
+              <li><a href="{{ "/filters/" | append: "#" | append: doc.title | prepend: site.baseurl }}">{{ doc.title }}</a></li>
+              {% endfor %}
             </ul>
           </li>
-          <li><a href="#">Nav Item 2</a></li>
+          {% endfor %}
+          <li><a href="https://github.com/Shopify/liquid">Source on GitHub</a></li>
           <li><a href="#">Nav Item 3</a></li>
           <li><a href="#">Nav Item 4</a></li>
         </ul>

_sass/_base.scss

@@ -135,3 +135,38 @@ hr {
   background-color: lighten($color-slate, 50%);
   margin-bottom: $spacing-unit/2;
 }
+
+table {
+  width: 100%;
+  overflow: auto;
+  display: block;
+  margin: 15px 0;
+  border-collapse: collapse;
+  thead {
+    margin: 0;
+    padding: 0;
+    border: 0;
+    font-size: 100%;
+    font: inherit;
+    vertical-align: baseline;
+  }
+  th {
+    border: 1px solid #ddd;
+    padding: 6px 13px;
+    font-weight: bold;
+    text-align: center;
+  }
+  tbody {
+    vertical-align: middle;
+    border-color: inherit;
+  }
+  tr {
+    border-top: 1px solid #ccc;
+    background-color: #fff;
+    vertical-align: inherit;
+  }
+  td {
+    border: 1px solid #ddd;
+    padding: 6px 13px;
+  }
+}

about.md

@@ -1,11 +0,0 @@
----
-layout: page
-title: About
-permalink: /about/
----
-
-This is the base Jekyll theme. You can find out more info about customizing your Jekyll theme, as well as basic Jekyll usage documentation at [jekyllrb.com](http://jekyllrb.com/)
-
-You can find the source code for the Jekyll new theme at: [github.com/jglovier/jekyll-new](https://github.com/jglovier/jekyll-new)
-
-You can find the source code for Jekyll at [github.com/jekyll/jekyll](https://github.com/jekyll/jekyll)

css/main.scss

@@ -85,6 +85,7 @@ $on-laptop:        900px;
   width: $sidebar-width;
   height: 100vh;
   position: fixed;
+  overflow: scroll;
 }
 
 .sidebar--logo {
@@ -156,6 +157,10 @@ $on-laptop:        900px;
   color: $color-white;
 }
 
+.right {
+  float: right;
+}
+
 /*============================================================================
   Index
  ==============================================================================*/

feed.xml

@@ -4,8 +4,8 @@ layout: null
 <?xml version="1.0" encoding="UTF-8"?>
 <rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
   <channel>
-    <title>{{ site.title | xml_escape }}</title>
-    <description>{{ site.description | xml_escape }}</description>
+    <title>{{ site.data.site.title | xml_escape }}</title>
+    <description>{{ site.data.site.description | xml_escape }}</description>
     <link>{{ site.url }}{{ site.baseurl }}/</link>
     <atom:link href="{{ "/feed.xml" | prepend: site.baseurl | prepend: site.url }}" rel="self" type="application/rss+xml"/>
     <pubDate>{{ site.time | date_to_rfc822 }}</pubDate>

filters.md

@@ -0,0 +1,17 @@
+---
+title: Filters
+permalink: /filters/
+layout: page
+---
+
+{% for doc in site.filters %}
+<h3 class="component-link" id="{{ doc.title }}">{{ doc.title }}</h3>
+<div>
+  <span class="right">
+    <a href="https://github.com/Shopify/liquid/edit/gh-pages/{{ doc.relative_path }}">
+      Improve documentation for {{doc.title}}.
+    </a>
+  </span>
+  {{ doc.output }}
+</div>
+{% endfor %}