Documentation on how to build navigation

docs/.gitignore

@@ -2,3 +2,4 @@ _site/
 *.swp
 pkg/
 test/
+.idea/

docs/_config.yml

@@ -16,6 +16,8 @@ collections:
   posts:
     permalink: /news/:year/:month/:day/:title/
     output: true
+  tutorials:
+    output: true
 
 name: Jekyll • Simple, blog-aware, static sites
 description: Transform your plain text into static websites and blogs

docs/_data/docs.yml

@@ -25,6 +25,7 @@
   - templates
   - permalinks
   - pagination
+  - navigation
   - plugins
   - themes
   - extras

docs/_data/tutorials.yml

@@ -0,0 +1,8 @@
+- title: Tutorials
+  tutorials:
+  - home
+  - navigation
+
+#- title: Another section
+#  tutorials:
+#  - sample

docs/_docs/datafiles.md

@@ -71,6 +71,9 @@ You can now render the list of members in a template:
 {% endraw %}
 ```
 
+{: .note .info }
+If your Jekyll site has a lot of pages, such as with documentation websites, see the detailed examples in [how to build robust navigation for your site]({% link _tutorials/navigation.md %}).
+
 ## Example: Organizations
 
 Data files can also be placed in sub-folders of the `_data` folder. Each folder
@@ -150,3 +153,5 @@ author: dave
 
 {% endraw %}
 ```
+
+For information on how to build robust navigation for your site (especially if you have a documentation website or another type of Jekyll site with a lot of pages to organize), see [Navigation](../navigation).

docs/_includes/primary-nav-items.html

@@ -5,6 +5,9 @@
   <li class="{% if page.url contains '/docs/' %}current{% endif %}">
     <a href="/docs/home/">Docs</a>
   </li>
+  <li class="{% if page.url contains '/tutorials/' %}current{% endif %}">
+    <a href="/tutorials/home/">Tutorials</a>
+  </li>
   <li class="{% if page.author %}current{% endif %}">
     <a href="/news/">News</a>
   </li>
@@ -15,6 +18,6 @@
     <a href="/help/">Help</a>
   </li>
   <li>
-    <a href="{{ site.repository }}"><span class="hide-on-mobiles">View on </span>GitHub</a>
+    <a href="{{ site.repository }}">GitHub</a>
   </li>
 </ul>

docs/_includes/section_nav_tutorials.html

@@ -0,0 +1,39 @@
+{% comment %}
+Map grabs the tutorials sections, giving us an array of arrays. Join, flattens all
+the items to a comma delimited string. Split turns it into an array again.
+{% endcomment %}
+{% assign tutorials = site.data.tutorials | map: 'tutorials' | join: ',' | split: ',' %}
+
+{% comment %}
+Because this is built for every page, lets find where we are in the ordered
+document list by comparing url strings. Then if there's something previous or
+next, lets build a link to it.
+{% endcomment %}
+
+{% for tutorial in tutorials %}
+  {% assign tutorial_url = tutorial | prepend:"/tutorials/" | append:"/" %}
+  {% if tutorial_url == page.url %}
+    <div class="section-nav">
+      <div class="left align-right">
+          {% if forloop.first %}
+            <span class="prev disabled">Back</span>
+          {% else %}
+            {% assign previous = forloop.index0 | minus: 1 %}
+            {% assign previous_page = tutorials[previous] | prepend:"/tutorials/" | append:"/" %}
+            <a href="{{ previous_page }}" class="prev">Back</a>
+          {% endif %}
+      </div>
+      <div class="right align-left">
+          {% if forloop.last %}
+            <span class="next disabled">Next</span>
+          {% else %}
+            {% assign next = forloop.index0 | plus: 1 %}
+            {% assign next_page = tutorials[next] | prepend:"/tutorials/" | append:"/" %}
+            <a href="{{ next_page }}" class="next">Next</a>
+          {% endif %}
+      </div>
+    </div>
+    <div class="clear"></div>
+    {% break %}
+  {% endif %}
+{% endfor %}

docs/_includes/tutorials_contents.html

@@ -0,0 +1,10 @@
+<div class="unit one-fifth hide-on-mobiles">
+  <aside>
+    {% for section in site.data.tutorials %}
+    <h4>{{ section.title }}</h4>
+
+   {% include tutorials_ul.html items=section.tutorials %}
+
+    {% endfor %}
+  </aside>
+</div>

docs/_includes/tutorials_contents_mobile.html

@@ -0,0 +1,10 @@
+<div class="docs-nav-mobile unit whole show-on-mobiles">
+  <select onchange="if (this.value) window.location.href=this.value">
+    <option value="">Navigate the tutorials…</option>
+    {% for section in site.data.tutorials %}
+    <optgroup label="{{ section.title }}">
+      {% include tutorials_option.html items=section.tutorials %}
+    </optgroup>
+    {% endfor %}
+  </select>
+</div>

docs/_includes/tutorials_option.html

@@ -0,0 +1,5 @@
+{% for item in include.items %}
+  {% assign item_url = item | prepend:"/tutorials/" | append:"/" %}
+  {% assign tutorial = site.tutorials | where: "url", item_url | first %}
+  <option value="{{ tutorial.url }}">{{ tutorial.title }}</option>
+{% endfor %}

docs/_includes/tutorials_ul.html

@@ -0,0 +1,7 @@
+<ul>
+{% for item in include.items %}
+  {% assign item_url = item | prepend:"/tutorials/" | append:"/" %}
+  {% assign p = site.tutorials | where:"url", item_url | first %}
+  <li class="{% if item_url == page.url %}current{% endif %}"><a href="{{ p.url }}">{{ p.title }}</a></li>
+{% endfor %}
+</ul>

docs/_layouts/tutorials.html

@@ -0,0 +1,27 @@
+---
+layout: default
+---
+
+  <section class="docs">
+    <div class="grid">
+
+      {% include tutorials_contents_mobile.html %}
+
+      <div class="unit four-fifths">
+        <article>
+          <div class="improve right hide-on-mobiles">
+            <a href="https://github.com/jekyll/jekyll/edit/master/tutorials/{{ page.path }}"><i
+                    class="fa fa-pencil"></i> &nbsp;Improve this page</a>
+          </div>
+          <h1>{{ page.title }}</h1>
+          {{ content }}
+          {% include section_nav_tutorials.html %}
+        </article>
+      </div>
+
+      {% include tutorials_contents.html %}
+
+      <div class="clear"></div>
+
+    </div>
+  </section>

docs/_sass/_style.scss

@@ -1031,3 +1031,8 @@ code.output {
   clip: rect(0, 0, 0, 0);
   border: 0;
 }
+
+.result {
+  border: 1px solid yellow;
+  padding: 10px;
+}

docs/_tutorials/index.md

@@ -0,0 +1,35 @@
+---
+layout: tutorials
+title: Tutorials
+permalink: /tutorials/home/
+redirect_from: /tutorials/index.html
+---
+
+In contrast to [Docs](../docs), Tutorials provide more detailed, narrative instruction that cover a variety of Jekyll topics and scenarios. Tutorials might contain the following:
+
+* Step-by-step processes through particular scenarios or challenges
+* Full walk-throughs using sample data, showing inputs and results from the sample data
+* Detailed explanation about the pros and cons for different Jekyll strategies
+* End-to-end instruction in developing a complete feature on a Jekyll site
+* Instruction that combines various techniques from across the docs
+
+In short, tutorials aren't the core reference information in docs. They walk users through processes from beginning to end.
+
+{: .info .note}
+**Note:** The Tutorials section is new, so there aren't many tutorials yet. You can add a tutorial here to help popular this section.
+
+Some of these techniques might even guide you through a supporting tool, script, service, or other hack used with your Jekyll site. Feel free to include tutorials involving external services with Jekyll as well. However, note that Jekyll in no way endorses any third-party tools mentioned in tutorials.
+
+## How to contribute a tutorial
+
+We welcome your tutorial contributions. To add your tutorial:
+
+1. Fork the Jekyll project by clicking the **Fork** button in the upper-right corner of the [jekyll/jekyll project Github repo](https://github.com/jekyll/jekyll/).
+2. Add your tutorial in the `_tutorials` collection.
+3. Make sure your tutorial has the same front matter items as other tutorial items.
+5. Add a reference to your tutorial filename in `_data/tutorials.yml`. This allows your tutorial to appear in the Tutorials sidebar.
+6. Follow the regular git workflow to submit the pull request.
+
+When you submit your pull request, the Jekyll documentation team will review your contribution and either merge it or suggest edits.
+
+