How to use Jekyll-paginate without index.html?

Question

I'm trying to build my blog on Github pages and I have to use Jekyll-paginate for obvious reasons. The problem is, I don't use the index.html page for anything other than a welcome page. I have a separate page called index.html in a folder called articles, thus the url for the blog should be xyz.github.io/articles/.

However, this presents a major problem - apparently jekyll-paginate refuses to work without an explicit index.html in the root directory of the blog. So, I tried using jekyll-paginate-v2 which has no such restrictions, and it worked perfectly!

However, github pages don't support jekyll-paginate-v2, and thus, I'm back to square 1. What should I do?

NOTE : Here's my code:

index.md

---
layout: home
title: SomuSysAdmin
---

If you're new to this site and have no idea what's going on, first go and read the [About](about.md) section of the blog.

Here's a list of all the major articles this blog contains: 

## [Red Hat Certified Systems Administrator (RHCSA) Guide]({% post_url 2017-09-11-RHCSA %})

And here's my _config.yml:

# -----------------------------------------------------------------------------
#  User configuration
# -----------------------------------------------------------------------------

title:               SomuSysAdmin

# The unique resource location of your page.
# Set to `https://<username>.github.io` when hosting on GitHub Pages
url:                 https://somuSysAdmin.github.io

# Set to '' when hosting a blog on GitHub Pages, ie on `//<username>.github.io`
# Set to '/<reponame>' when using the `gh-pages` branch of a repository
baseurl:             ''

# A very short description of your page
tagline:             Easiest way to earn some SysAdmin mojo!

# A short description of the page, used in the sidebar and as fallback for the meta description tag.
# Markdown enabled, but don't use more than one paragraph (enforced by `>`)
description:         >
  A short set of notes and pointers concerning everything I know about System Administration.
# This should be the same author as first entry in `_data/authors.yml`
author:
  name:              Somenath Sinha
  email:             [email protected]

# Fallback image and color
image:               /assets/img/nap.jpg
color:               '#4ea97e'

# The font used for headings. Expects a string that is a valid CSS font-family value.
font_heading:        "'Roboto Slab', Helvetica, Arial, sans-serif"

# The text font. Expects a string that is a valid CSS font-family value.
font:                "'Noto Sans', Helvetica, Arial, sans-serif"

# The string encoding what fonts to fetch from Google Fonts.
# See: https://qwtel.com/hydejack/docs/configuration/
google_fonts:        Roboto+Slab:700|Noto+Sans:400,400i,700,700i

# If you do not use a Google Fonts, uncomment the line below
# no_google_fonts:     true

# Set your Google Analytics id to receive `pageview` events.
# To remove Google Anaylics from your page, remove the line below.
google_analytics:    <UA-XXXXXXXX-X>

# Setting a disqus shortname will enable the comment section on pages with `comments: true` in the front matter
disqus_shortname:    somusa

# This text will appear in the footer of every page. Markdown enabled.
copyright:           '&copy; 2017 Somenath Sinha. All rights reserved.'

# Format of the permalinks
permalink:           pretty

# Pagination configuration (used by the `blog` layout)
paginate:            5
paginate_path:       '/page-:num/'

# If you are upgrading form a v5 verison of Hydejack, uncomment the two lines below,
# so that the location of the feed XML stays the same.
# feed:
#   path:              atom.xml

# Set to true when building with the `--lsi` option
# See: https://jekyllrb.com/docs/variables/#site-variables
# use_lsi:             true

# Set to `true` if you don't want to show an icon after each link that opens to an external site
# no_mark_external:    true

# Uncomment this line if third party plugins fail to work with dynimically loaded pages
# disable_push_state:  true

# Uncomment this line if want to disable the touch drawer on mobile
# disable_drawer: true

# -----------------------------------------------------------------------------
#  Collections
# -----------------------------------------------------------------------------

collections:
  featured_categories:
    permalink:       /category/:name/
    output:          true
  featured_tags:
    permalink:       /tag/:name/
    output:          true
  projects:
    permalink:       /projects/:path/
    output:          true

# -----------------------------------------------------------------------------
#  Advanced configuration
# -----------------------------------------------------------------------------

gems:
  - jekyll-default-layout
  - jekyll-feed
  - jekyll-optional-front-matter
  - jekyll-paginate
  - jekyll-redirect-from
  - jekyll-relative-links
  - jekyll-sitemap

exclude:
  - README.md
  - node_modules
  - package.json
  - package-lock.json
  - Gemfile
  - Gemfile.lock

kramdown:
  footnote_backlink: '&#x21a9;&#xfe0e;'
  math_engine:       mathjax
  math_engine_opts:
    preview:         true
    preview_as_code: true

compress_html:
  comments:          ["<!-- ", " -->"]
  clippings:         all
  endings:           all
  ignore:
    envs:            [development]

sass:
  style:             compressed

Here's the content of my articles/index.md:

---
layout  : blog
title   : Articles
menu    : true
order   : 1
---

So, is there any way I can use jekyll-paginate without using an explicit index.html?

Here's what happens when I try to run jekyll on my present blog without an index.html:

$ bundle exec jekyll serve --incremental
Configuration file: D:/Git/blog/_config.yml
      Deprecation: The 'gems' configuration option has been renamed to 'plugins'. Please update your config file accordingly.
      Source: D:/Git/blog
      Destination: D:/Git/blog/_site
Incremental build: enabled
    Generating...
      Pagination: Pagination is enabled, but I couldn't find an index.html page to use as the pagination template. Skipping pagination.
                    done in 1.736 seconds.
Please add the following to your Gemfile to avoid polling for changes:
    gem 'wdm', '>= 0.1.0' if Gem.win_platform?
Auto-regeneration: enabled for 'D:/Git/blog'
  Server address: http://127.0.0.1:4000/
  Server running... press ctrl-c to stop.

As you can see, the pagination doesn't work at all! So, how do I fix it? I'm new to markdown and jekyll, so I may even be missing something obvious! Please help me fix it!

Answer 1

The documentation for Jekyll pagination says:

Pagination only works within HTML files

Pagination does not work from within Markdown or Textile files from your Jekyll site. Pagination works when called from within the HTML file, named index.html, which optionally may reside in and produce pagination from within a subdirectory, via the paginate_path configuration value.

So if you want your blog to be on URL /articles/ and /articles/N/, specify this in your configuration:

paginate_path: "/articles/:num/"

And place an index.html file inside articles directory, which lists the posts for the current page:

<!-- This loops through the paginated posts -->
{% for post in paginator.posts %}
  <h1><a href="{{ post.url }}">{{ post.title }}</a></h1>
  <p class="author">
    <span class="date">{{ post.date }}</span>
  </p>
  <div class="content">
    {{ post.content }}
  </div>
{% endfor %}

<!-- Pagination links -->
<div class="pagination">
  {% if paginator.previous_page %}
    <a href="{{ paginator.previous_page_path }}" class="previous">Previous</a>
  {% else %}
    <span class="previous">Previous</span>
  {% endif %}
  <span class="page_number ">Page: {{ paginator.page }} of {{ paginator.total_pages }}</span>
  {% if paginator.next_page %}
    <a href="{{ paginator.next_page_path }}" class="next">Next</a>
  {% else %}
    <span class="next ">Next</span>
  {% endif %}
</div>

(See the documentation for more snippets and configuration details.)

EDIT: I think your problem was your paginate_path setting. You set it to '/page-:num/', therefore Jekyll Paginate looked for index.html in your site root.