Manual ordering of episodes and extras

Co-authored-by: stamper <tbyhdgs@gmail.com>

_includes/aio-script.md

 {% comment %}
 As a maintainer, you don't need to edit this file.
-If you notice that something doesn't work, please 
+If you notice that something doesn't work, please
 open an issue: https://github.com/carpentries/styles/issues/new
 {% endcomment %}
 
+{% include manual_episode_order.html %}
+
 <script>
   window.onload = function() {
     var lesson_episodes = [
-    {% for episode in site.episodes %}
+    {% for lesson_episode in lesson_episodes %}
+      {% if site.episode_order %}
+        {% assign episode = site.episodes | where: "slug", lesson_episode | first %}
+      {% else %}
+        {% assign episode = lesson_episode %}
+      {% endif %}
     "{{ episode.url}}"{% unless forloop.last %},{% endunless %}
     {% endfor %}
     ];
@@ -30,9 +37,14 @@ open an issue: https://github.com/carpentries/styles/issues/new
     }
   }
 </script>
-{% comment %}
-Create an anchor for every episode.
-{% endcomment %}
-{% for episode in site.episodes %}
-<article id="{{ episode.url }}"></article>
+
+{% comment %} Create an anchor for every episode.  {% endcomment %}
+
+{% for lesson_episode in lesson_episodes %}
+  {% if site.episode_order %}
+    {% assign episode = site.episodes | where: "slug", lesson_episode | first %}
+  {% else %}
+    {% assign episode = lesson_episode %}
+  {% endif %}
+  <article id="{{ episode.url }}"></article>
 {% endfor %}

_includes/all_keypoints.html

@@ -3,10 +3,16 @@
 {% endcomment %}
 
 {% include base_path.html %}
+{% include manual_episode_order.html %}
 
 <h2>Key Points</h2>
 <table class="table table-striped">
-{% for episode in site.episodes %}
+{% for lesson_episode in lesson_episodes %}
+  {% if site.episode_order %}
+    {% assign episode = site.episodes | where: "slug", lesson_episode | first %}
+  {% else %}
+    {% assign episode = lesson_episode %}
+  {% endif %}
   {% unless episode.break %}
     <tr>
       <td class="col-md-3">

_includes/episode_navbar.html

@@ -9,11 +9,17 @@ need to re-assign it here
   Navigation bar for an episode.
 {% endcomment %}
 
+{% include manual_episode_order.html %}
+{% comment %}
+    'previous_episode' and 'next_episodes' are defined in 'manual_episode_order.html'.
+    These replace 'page.previous' and 'page.next' objects, correspondingly.
+{% endcomment %}
+
 <div class="row">
   <div class="col-xs-1">
     <h3 class="text-left">
-      {% if page.previous.url %}
-      <a href="{{ relative_root_path }}{{ page.previous.url }}"><span class="glyphicon glyphicon-menu-left" aria-hidden="true"></span><span class="sr-only">previous episode</span></a>
+      {% if previous_episode %}
+      <a href="{{ relative_root_path }}{{ previous_episode.url }}"><span class="glyphicon glyphicon-menu-left" aria-hidden="true"></span><span class="sr-only">previous episode</span></a>
       {% else %}
       <a href="{{ relative_root_path }}/"><span class="glyphicon glyphicon-menu-up" aria-hidden="true"></span><span class="sr-only">lesson home</span></a>
       {% endif %}
@@ -26,8 +32,8 @@ need to re-assign it here
   </div>
   <div class="col-xs-1">
     <h3 class="text-right">
-      {% if page.next.url %}
-      <a href="{{ relative_root_path }}{{ page.next.url }}"><span class="glyphicon glyphicon-menu-right" aria-hidden="true"></span><span class="sr-only">next episode</span></a>
+      {% if next_episode %}
+      <a href="{{ relative_root_path }}{{ next_episode.url }}"><span class="glyphicon glyphicon-menu-right" aria-hidden="true"></span><span class="sr-only">next episode</span></a>
       {% else %}
       <a href="{{ relative_root_path }}/"><span class="glyphicon glyphicon-menu-up" aria-hidden="true"></span><span class="sr-only">lesson home</span></a>
       {% endif %}

_includes/manual_episode_order.html

+{% comment %}
+    This file enables manual episode ordering until
+    GitHub Pages switches to Jekyll that supports it
+    without any major hackery. Note, some logic will
+    be required even when this transition happens
+    but it won't be as involved as what we have to do
+    in this file.
+
+    To order lesson episodes or extras manually
+    (instead of the default alpha-numerical order),
+    create array variables 'episode_order' and
+    'extras_order' in `_config.yml` like so:
+
+    episode_order:
+      - episodeA
+      - episodeB
+
+    extras_order:
+      - extraA
+      - extraB
+
+    Note that "Reference" page is currently  always
+    added to "Extras" as the first item.
+
+    The main outcomes of the code in this file are:
+     - 'lesson_episodes' variable that replaces
+       'site.episodes' variable when manual episode
+       order is defined.
+     - 'lesson_extras' variable that replaces
+       'site.extras' variable when manual ordering of
+       files in '_extras' is used
+       - 'previous_episode' and 'next_episode' objects
+       that replace 'page.previous' and 'page.next' variables,
+       correspondingly, and that have such properties
+       as 'url' and 'title' and that are used in
+       'episode_navbar.html'.
+
+    When episode order is specified manualy, the 'lesson_episodes'
+    variable contains a list of episode names ("slugs", to be precise;
+    "slug" is the episode name without '.md').  Therefore, when we
+    iterate over 'lesson_episodes' (in syllabus.html and navbar.html) ,
+    we have to check whether we use manual episode ordering and, if so,
+    find the corresponding episode object. This is what we do with the
+    following code in every loop over 'lesson_episodes':
+
+        {% if site.episode_order %}
+          {% assign episode = site.episodes | where: "slug", lesson_episode | first %}
+        {% else %}
+          {% assign episode = lesson_episode %}
+        {% endif %}
+{% endcomment %}
+
+<!-- Manual ordering of Episodes begins here -->
+
+{% if site.episode_order %}
+    {% assign lesson_episodes = site.episode_order %}
+{% else %}
+    {% assign lesson_episodes = site.episodes %}
+{% endif %}
+
+
+{% comment %}
+    If 'episode_order' is defined, we need to determine
+    - previous episode object ('previous_episode')
+    - and next episode object ('next_episode')
+{% endcomment %}
+
+
+{% if site.episode_order %}
+  {% for lesson_episode in lesson_episodes %}
+
+    {% comment %}
+        We iterate over the specified lesson episodes using
+        a 'for' loop because we can use
+        'forloop.first', 'forloop.last', and 'forloop.index0'.
+    {% endcomment %}
+
+    {% unless lesson_episode == page.slug %} {% continue %} {% endunless %}
+
+    {% if forloop.first %}
+      {% assign previous_episode = nil %}
+    {% else %}
+      {% assign p_idx = forloop.index0 | minus: 1 %}
+      {% assign p_name = lesson_episodes[p_idx] %}
+      {% assign previous_episode = site.episodes | where: "slug", p_name | first %}
+    {% endif %}
+
+    {% if forloop.last == true %}
+      {% assign next_episode = nil %}
+    {% else %}
+      {% assign n_idx = forloop.index0 | plus: 1 %}
+      {% assign n_name = lesson_episodes[n_idx] %}
+      {% assign next_episode = site.episodes | where: "slug", n_name | first %}
+    {% endif %}
+  {% endfor %}
+{% else %}
+  {% assign previous_episode = page.previous %}
+  {% assign next_episode  = page.next %}
+{% endif %}
+
+<!-- Manual ordering of Extras begins here -->
+
+{% if site.extras_order %}
+    {% assign lesson_extras = site.extras_order %}
+{% else %}
+    {% assign lesson_extras = site.extras %}
+{% endif %}
+
+{% comment %}
+    We do not need to determine "previous" or "next" extra.
+{% endcomment %}

_includes/navbar.html

@@ -3,6 +3,7 @@
 {% endcomment %}
 
 {% include gh_variables.html %}
+{% include manual_episode_order.html %}
 
 <nav class="navbar navbar-default">
   <div class="container-fluid">
@@ -51,7 +52,12 @@
         <li class="dropdown">
           <a href="{{ relative_root_path }}/" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Episodes <span class="caret"></span></a>
           <ul class="dropdown-menu">
-            {% for episode in site.episodes %}
+            {% for lesson_episode in lesson_episodes %}
+            {% if site.episode_order %}
+              {% assign episode = site.episodes | where: "slug", lesson_episode | first %}
+            {% else %}
+              {% assign episode = lesson_episode %}
+            {% endif %}
             <li><a href="{{ relative_root_path }}{{ episode.url }}">{{ episode.title }}</a></li>
             {% endfor %}
 	    <li role="separator" class="divider"></li>
@@ -66,7 +72,12 @@
           <a href="{{ relative_root_path }}/" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Extras <span class="caret"></span></a>
           <ul class="dropdown-menu">
             <li><a href="{{ relative_root_path }}{% link reference.md %}">Reference</a></li>
-            {% for extra in site.extras %}
+            {% for lesson_extra in lesson_extras %}
+            {% if site.extras_order %}
+              {% assign extra = site.extras | where: "slug", lesson_extra | first %}
+            {% else %}
+              {% assign extra = lesson_extra %}
+            {% endif %}
             <li><a href="{{ relative_root_path }}{{ extra.url }}">{{ extra.title }}</a></li>
             {% endfor %}
           </ul>

_includes/syllabus.html

@@ -4,13 +4,21 @@
   Display syllabus in tabular form.
   Days are displayed if at least one episode has 'start = true'.
 {% endcomment %}
+
+{% include manual_episode_order.html %}
+
 <div class="syllabus">
   <h2 id="schedule">Schedule</h2>
 
   {% assign lesson_number = 0 %}
   {% assign day = 0 %}
   {% assign multiday = false %}
-  {% for episode in site.episodes %}
+  {% for lesson_episode in lesson_episodes %}
+    {% if site.episode_order %}
+      {% assign episode = site.episodes | where: "slug", lesson_episode | first %}
+    {% else %}
+      {% assign episode = lesson_episode %}
+    {% endif %}
     {% if episode.start %}{% assign multiday = true %}{% break %}{% endif %}
   {% endfor %}
   {% assign current = site.start_time %}
@@ -22,7 +30,12 @@
     <td class="col-md-3"><a href="{{ relative_root_path }}{% link setup.md %}">Setup</a></td>
     <td class="col-md-7">Download files required for the lesson</td>
   </tr>
-  {% for episode in site.episodes %}
+  {% for lesson_episode in lesson_episodes %}
+    {% if site.episode_order %}
+      {% assign episode = site.episodes | where: "slug", lesson_episode | first %}
+    {% else %}
+      {% assign episode = lesson_episode %}
+    {% endif %}
     {% if episode.start %} {% comment %} Starting a new day? {% endcomment %}
       {% assign day = day | plus: 1 %}
       {% if day > 1 %} {% comment %} If about to start day 2 or later, show finishing time for previous day {% endcomment %}

bin/boilerplate/_extras/figures.md

@@ -3,11 +3,17 @@ title: Figures
 ---
 
 {% include base_path.html %}
+{% include manual_episode_order.html %}
 
 <script>
   window.onload = function() {
     var lesson_episodes = [
-    {% for episode in site.episodes %}
+    {% for lesson_episode in lesson_episodes %}
+      {% if site.episode_order %}
+        {% assign episode = site.episodes | where: "slug", lesson_episode | first %}
+      {% else %}
+        {% assign episode = lesson_episode %}
+      {% endif %}
     "{{ episode.url }}"{% unless forloop.last %},{% endunless %}
     {% endfor %}
     ];
@@ -58,10 +64,15 @@ title: Figures
     }
   }
 </script>
-{% comment %}
-Create anchor for each one of the episodes.
-{% endcomment %}
-{% for episode in site.episodes %}
+
+{% comment %} Create anchor for each one of the episodes.  {% endcomment %}
+
+{% for lesson_episode in lesson_episodes %}
+  {% if site.episode_order %}
+    {% assign episode = site.episodes | where: "slug", lesson_episode | first %}
+  {% else %}
+    {% assign episode = lesson_episode %}
+  {% endif %}
 <article id="{{ episode.url }}" class="figures"></article>
 {% endfor %}