feature(index): add pagination support (#19)

Gemfile

@@ -4,4 +4,5 @@ source "https://rubygems.org"
 gemspec
 
 gem "jekyll", "3.9.2"
+gem "jekyll-paginate", "1.1.0"
 gem "kramdown-parser-gfm", "1.1.0"

Gemfile.lock

@@ -33,6 +33,7 @@ GEM
       pathutil (~> 0.9)
       rouge (>= 1.7, < 4)
       safe_yaml (~> 1.0)
+    jekyll-paginate (1.1.0)
     jekyll-sass-converter (1.5.2)
       sass (~> 3.4)
     jekyll-watch (2.2.1)
@@ -68,6 +69,7 @@ PLATFORMS
 DEPENDENCIES
   bundler (~> 2.2.30)
   jekyll (= 3.9.2)
+  jekyll-paginate (= 1.1.0)
   jekyll-theme-guardian!
   kramdown-parser-gfm (= 1.1.0)
   rake (~> 12.0)

README.md

@@ -4,6 +4,18 @@
 
 ## Installation
 
+### Remote Theme (Preferred)
+
+Add this line to your Jekyll site's `_config.yml`:
+
+```yaml
+remote_theme: widen/jekyll-theme-guardian@<TAG>
+```
+
+See [releases](https://github.com/Widen/jekyll-theme-guardian/releases) for the most up-to-date tag to reference.
+
+### Standard Ruby Gem
+
 Add this line to your Jekyll site's `Gemfile`:
 
 ```ruby
@@ -43,9 +55,20 @@ guardian:
     disqus_shortname: <DISQUS_SHORTNAME>
 ```
 
+This theme now properly leverages the `jekyll-pagination` plugin for blog posts. Ensure your site specifies proper [pagination configuration](https://jekyllrb.com/docs/pagination/):
+
+```yaml
+paginate: 5
+paginate_path: "/blog/page/:num/"
+```
+
+If pagination configuration is not defined, then all posts will be rendered and paginator elements will be hidden.
+
 ### Layouts
 
 * `default` - includes a header, content, and footer section
+* `index` - extends `default`, used as a blog index page (with paginated support for posts), if content is provided it will be rendered _before_ the post list
+* `page` - extends `default`, used for pages
 * `post` - extends `default` and optionally includes a Disqus comment block
 
 ### includes

_config.yml

@@ -1,13 +1,19 @@
 # theme configuration
 guardian:
   style:
-    logo_url: https://embed.widencdn.net/img/widen/c17yrvuaac/400px@2x/Widen Engineering White Logo.png?u=mcuc7i
-    header_background_url: https://embed.widencdn.net/img/widen/m4ml1kuspv/exact/1680x90_Engineering Blog Banner.png?keep=c&crop=yes&u=ksmgip
+    logo_url: https://embed.widencdn.net/img/widen/c17yrvuaac/400px@2x/widen-engineering-white-logo.png
+    header_background_url: https://embed.widencdn.net/img/widen/m4ml1kuspv/exact/widen-engineering-blog-banner.png?keep=c&crop=yes
   social_links:
-    twitter: widendev
+    twitter: acquiadev
     github_org: widen
     github_repo: jekyll-theme-guardian
-    email_subscription_url: https://www.widen.com
+    email_subscription_url:
   tracking:
     google_analytics_code:
     disqus_shortname:
+
+paginate: 5
+paginate_path: "/blog/page/:num/"
+
+plugins:
+  - jekyll-paginate

_includes/footer.html

@@ -15,8 +15,12 @@
         <nav aria-label="Social media links">
           <ul class="site-social-links inline">
               <li><a target="_blank" title="RSS Feed" href="{{ "/feed.xml" | relative_url }}"><ion-icon name="logo-rss"></ion-icon></a></li>
+            {% if site.guardian.social_links.github_org %}
               <li><a target="_blank" title="GitHub" href="https://github.com/{{ site.guardian.social_links.github_org }}"><ion-icon name="logo-github"></ion-icon></a></li>
+            {% endif %}
+            {% if site.guardian.social_links.twitter %}
               <li><a target="_blank" title="Twitter" href="https://twitter.com/{{ site.guardian.social_links.twitter }}"><ion-icon name="logo-twitter"></ion-icon></a></li>
+            {% endif %}
           </ul>
         </nav>
         <p>© Copyright {{ site.time | date: '%Y' }}, <a title="Widen Homepage" target="_blank" href="http://widen.com">Widen Enterprises, Inc.</a></p>

_layouts/index.html

@@ -0,0 +1,44 @@
+---
+layout: default
+---
+
+{{ content }}
+
+<div class="posts">
+{% assign posts = site.posts %}
+{% if paginator %}
+    {% assign posts = paginator.posts %}
+{% endif %}
+{% for post in posts %}
+    <article>
+        <h1>
+        <a href="{{ post.url | relative_url }}">{{ post.title }}</a>
+        </h1>
+
+        <p class="posts-excerpt">
+        {% if post.excerpt != '' %}
+            {{ post.excerpt | truncatewords: 50 | remove: '<p>' | remove: '</p>' }}
+        {% else %}
+            {{ post.content | strip_html | truncatewords: 50 }}
+        {% endif %}
+        </p>
+
+        <time>{{ post.date | date: "%b %-d, %Y" }}</time> • {{post.author}}
+    </article>
+{% endfor %}
+
+{% if paginator %}
+    <div class="paginator">
+      {% if paginator.previous_page %}
+        <a href="{{ paginator.previous_page_path }}"><ion-icon name="arrow-back-outline"></ion-icon>Newer</a>
+      {% else %}
+        <span><ion-icon name="arrow-back-outline"></ion-icon>Newer</span>
+      {% endif %}
+      {% if paginator.next_page %}
+        <a href="{{ paginator.next_page_path }}">Older<ion-icon name="arrow-forward-outline"></ion-icon></a>
+      {% else %}
+        <span>Older<ion-icon name="arrow-forward-outline"></ion-icon></span>
+      {% endif %}
+    </div>
+</div>
+{% endif %}

_sass/_index.scss

@@ -12,4 +12,17 @@
     font-size: 1.65rem;
     color: $dark-grey;
   }
+
+  .paginator {
+    display: flex;
+    gap: 16px;
+    justify-content: space-between;
+
+    a, span {
+      padding: 8px;
+      display: inline-flex;
+      align-items: center;
+      gap: 4px;
+    }
+  }
 }

index.html

@@ -1,24 +1,3 @@
 ---
-layout: default
+layout: index
 ---
-<div class="posts">
-    <ul>
-      {% for post in site.posts %}
-        <article>
-          <h1>
-            <a href="{{ post.url | relative_url }}">{{ post.title }}</a>
-          </h1>
-
-          <p class="posts-excerpt">
-            {% if post.excerpt != '' %}
-              {{ post.excerpt | truncatewords: 50 | remove: '<p>' | remove: '</p>' }}
-            {% else %}
-              {{ post.content | strip_html | truncatewords: 50 }}
-            {% endif %}
-          </p>
-
-          <time>{{ post.date | date: "%b %-d, %Y" }}</time> • {{post.author}}
-        </article>
-      {% endfor %}
-    </ul>
-</div>