{"id":19488662,"url":"https://github.com/ibrado/jekyll-paginate-content","last_synced_at":"2025-04-25T18:32:48.328Z","repository":{"id":56878710,"uuid":"114933900","full_name":"ibrado/jekyll-paginate-content","owner":"ibrado","description":"Paginate::Content - Split your Jekyll pages, posts, etc. into multiple pages automatically. Single-page view, pager, SEO support, self-adjusting links, multipage-aware Table Of Contents.","archived":false,"fork":false,"pushed_at":"2022-09-18T21:56:31.000Z","size":171,"stargazers_count":16,"open_issues_count":2,"forks_count":6,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-17T11:18:59.936Z","etag":null,"topics":["blogging","content-management-system","jekyll","jekyll-generator","jekyll-paginate","jekyll-plugin","paginate","plugin","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ibrado.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-12-20T21:44:32.000Z","updated_at":"2022-09-12T21:34:36.000Z","dependencies_parsed_at":"2022-08-20T22:30:58.397Z","dependency_job_id":null,"html_url":"https://github.com/ibrado/jekyll-paginate-content","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibrado%2Fjekyll-paginate-content","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibrado%2Fjekyll-paginate-content/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibrado%2Fjekyll-paginate-content/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibrado%2Fjekyll-paginate-content/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ibrado","download_url":"https://codeload.github.com/ibrado/jekyll-paginate-content/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250872408,"owners_count":21500810,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blogging","content-management-system","jekyll","jekyll-generator","jekyll-paginate","jekyll-plugin","paginate","plugin","ruby"],"created_at":"2024-11-10T21:04:50.048Z","updated_at":"2025-04-25T18:32:48.055Z","avatar_url":"https://github.com/ibrado.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Jekyll::Paginate::Content\n\n[![Gem Version](https://badge.fury.io/rb/jekyll-paginate-content.svg)](https://badge.fury.io/rb/jekyll-paginate-content)\n\n**You may read this documentation [split across several pages](https://ibrado.org/jpc/readme/).**\n\n*Jekyll::Paginate::Content* (JPC) is a plugin for [Jekyll](https://jekyllrb.com/) that automatically splits pages, posts, and other content into one or more pages. This can be at points where e.g. `\u003c!--page--\u003e` is inserted, or at the \u0026lt;h1\u0026gt; to \u0026lt;h6\u0026gt; headers. It mimics [jekyll-paginate-v2](https://github.com/sverrirs/jekyll-paginate-v2) (JPv2) naming conventions and features, so if you use that, you will be in familiar territory.\n\n**Features:** Automatic content splitting into several pages, single-page view, configurable permalinks, page trail/pager, SEO support, self-adjusting internal links, multipage-aware Table Of Contents.\n\n- [Jekyll::Paginate::Content](#jekyllpaginatecontent)\n  * [TL;DR](#tldr)\n    + [Manual](#manual)\n    + [Automatic, with config overrides and mixed syntax](#automatic-with-config-overrides-and-mixed-syntax)\n  * [Why use this?](#why-use-this)\n  * [Installation](#installation)\n  * [Configuration](#configuration)\n  * [Usage](#usage)\n  * [Setting up splitting](#setting-up-splitting)\n    + [Manual mode](#manual-mode)\n    + [HTML header mode](#html-header-mode)\n    + [Page headers and footers](#page-headers-and-footers)\n  * [Paginator Properties/Fields](#paginator-propertiesfields)\n    + [site.baseurl](#sitebaseurl)\n  * [Page/post properties](#pagepost-properties)\n    + [Setting custom properties](#setting-custom-properties)\n    + [Overriding and restoring properties](#overriding-and-restoring-properties)\n      - [Special values](#special-values)\n    + [Default properties](#default-properties)\n    + [Example: blog](#example-blog)\n    + [Example: slides/presentation](#example-slidespresentation)\n      - [Last slide](#last-slide)\n  * [Pagination trails](#pagination-trails)\n    + [Usage](#usage-1)\n    + [Page flipper](#page-flipper)\n  * [Table Of Contents (TOC)](#table-of-contents-toc)\n    + [Excluding sections](#excluding-sections)\n  * [Search Engine Optimization (SEO)](#search-engine-optimization-seo)\n    + [Unified approach](#unified-approach)\n  * [Demos](#demos)\n  * [Limitations](#limitations)\n  * [Contributing](#contributing)\n  * [License](#license)\n  * [Code of Conduct](#code-of-conduct)\n  * [Also by the Author](#also-by-the-author)\n\n## TL;DR\n\n### Manual\n\n```markdown\n---\ntitle: \"JPC demo: 3-page manual\"\nlayout: page\npaginate: true\n---\n\nThis shows up at the top of all pages.\n\u003c!--page_header--\u003e\n\nThis is page 1 of the JPC example.\n\n\u003ca name=\"lorem\"\u003e\u003c/a\u003eLorem ipsum dolor...\n\n\u003c!--page--\u003e\nThis is page 2 with a [link] to the first page which works in single or paged view.\n\n\u003c!--page--\u003e\nThis is the last page.\n\n\u003c!--page_footer--\u003e\nThis goes into the bottom of all pages.\n\n[link]: #lorem\n```\n[Live demo](https://ibrado.org/demos/jpc-3page-manual)\n\n### Automatic, with config overrides\n\n```markdown\n---\ntitle: \"JPC demo: 3-page auto\"\nlayout: page\npaginate: true\npaginate_content:\n  separator: h2\n  title: \":title :num/:max: :section\"\n  permalink: /page:numof:max.html\n---\n\n# Introduction\n\nHello!\n\n## What did something?\n\nThe quick brown fox...\n\n## What did it do?\n\n...jumped over the lazy dog.\n\n```\n\n[Live demo](https://ibrado.org/demos/jpc-3page-auto)\n\nSee other [demos](#demos).\n\n## Why use this?\n\n1. You want to split long posts and pages/articles/reviews, etc. into multiple pages, e.g. chapters;\n1. You want to offer faster loading times to your readers;\n1. You want to make slide/presentation-type content (see [demo](https://ibrado.org/jpc/slides/)!)\n1. You want more ad revenue from your Jekyll site;\n1. You wanna be the cool kid. :stuck_out_tongue:\n\n## What's new?\n\nv1.1.0 Layout overrides for e.g. slides; regenerate and other fixes\n\nv1.0.4 Allow inclusion in `_config.yml` plugins\n\nv1.0.3 Bugfixes; force option\n\nv1.0.2 Don't regenerate unnecessarily\n\n## Installation\n\nAdd the gem to your application's Gemfile:\n\n```ruby\ngroup :jekyll_plugins do\n  # other plugins here\n  gem 'jekyll-paginate-content'\nend\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself:\n\n    $ gem install jekyll-paginate-content\n\n## Configuration\n\nNo configuration is required to run *Jekyll::Paginate::Content*. If you want to tweak its behavior, you may set the following options in `_config.yml`:\n\n```yaml\n\npaginate_content:\n  #enabled: false                    # Default: true\n  debug: true                        # Show additional messages during run; default: false\n  #collection: pages, \"articles\"     # Which collections to paginate; default: pages and posts\n  collections:                       # Ditto, just a different way of writing it\n    - pages                          # Quotes are optional if collection names are obviously strings\n    - posts\n    - articles\n\n  auto: true                         # Set to true to search for the page separator even if you\n                                     #   don't set paginate: true in the front-matter\n                                     # Default: false\n\n  force: true                        # Set to true to force regeneration of pages; default: false\n\n  separator: \"\u003c!--split--\u003e\"          # The page separator; default: \"\u003c!--page--\u003e\"\n                                     # Can be \"h1\" to \"h6\" for automatic splitting\n                                     # Note: Setext (underline titles) only supports h1 and h2\n\n  header: \"\u003c!--head--\u003e\"              # The header separator; default: \"\u003c!--page_header--\u003e\"\n  footer: \"\u003c!--foot--\u003e\"              # The footer separator; default: \"\u003c!--page_footer--\u003e\"\n\n  permalink: '/borg:numof:max.html'  # Relative path to the new pages; default: \"/:num/\"\n                                     #   :num will be replaced by the current page number\n                                     #   :max will be replaced by the total number of page parts\n                                     # e.g. /borg7of9.html\n\n  single_page: '/full.html'          # Relative path to the single-page view; default: \"/view-all/\"\n                                     # Set to \"\" for no single page view\n\n  minimum: 1000                      # Minimum number of characters (including markup) in a page\n                                     # for automatic header splitting. \n                                     #   If a section is too short, the next section will be merged\n                                     # Default: none\n                                     \n  title: ':title - :num/:max'        # Title format of the split pages, default: original title\n                                     #   :num and :max are as in permalink,\n                                     #   :title is the original title\n                                     #   :section is the text of the first header\n\n  retitle_first: true                # Should the first part be retitled too? Default: false\n\n  trail:                             # The page trail settings: number of pages to list\n    before: 3                        #   before and after the current page\n    after: 3                         #   Omit or set to 0 for all pages (default)\n\n  seo_canonical: false               # Set link ref=\"canonical\" to the view-all page; default: true\n\n  prepend_baseurl: false             # Prepend the site.baseurl to paths; default: true\n\n  #properties:                       # Set properties per type of page, see below\n  #  all:\n  #    field1: value1\n  #    # ...etc...\n  #  first:\n  #    field2: value2\n  #    # ...etc...\n  #  part:\n  #    field3: value3\n  #     # ...etc...\n  #   last:\n  #    field4: value4\n  #    # ...etc...\n  #  single:\n  #    field5: value5\n  #    # ...etc...\n\n```\n\nHere's a cleaned-up version with the defaults:\n\n```yaml\n\npaginate_content:\n  #enabled: true\n  #debug: false\n\n  #collections:\n  #  - pages\n  #  - posts\n\n  #auto: false\n\n  #separator: \"\u003c!--page--\u003e\"\n  #header: \"\u003c!--page_header--\u003e\"\n  #footer: \"\u003c!--page_footer--\u003e\"\n\n  #permalink: '/:num/\"\n  #single_page: '/view-all/'\n  #minimum: 0\n\n  #title: ':title'\n  #retitle_first: false\n\n  #trail:\n  #  before: 0\n  #  after: 0\n\n  #seo_canonical: true\n\n  #prepend_baseurl: true\n\n  #properties:\n  #  all:\n  #  first:\n  #  part:\n  #  last:\n  #  single:\n\n```\n\n## Usage\n\nJust add a `paginate: true` entry to your front-matter:\n\n```yaml\n---\ntitle: Test post\nlayout: post\ndate: 2017-12-15 22:33:44\npaginate: true\n---\n```\n\nor set `auto` to `true` in your `_config.yml`:\n\n```yaml\npaginate_content:\n  auto: true\n```\n\nNote that using `auto` mode might be slower on your machine. \n\nYou may also override `_config.yml` settings for a particular file like so:\n\n```yaml\n---\ntitle: Test page\nlayout: page\npaginate_content:\n  permalink: '/page:numof:max.html'\n  single_page: '/full.html'\n---\n```\n\nYou don't need to specify `paginate: true` if you already have `paginate_content` in your front matter.\n\n## Splitting content\n\nHow your content is split depends on your `separator`:\n\n### Manual mode\n\nIf your `separator` is `\"\u003c!--page--\u003e\"`, just put that wherever you want a split to occur:\n\n```html\nThis is a page.\n\u003c!--page--\u003e\nThis is another page.\n```\n\n### HTML header mode\n\nIf you set your header to \"h1\" up to \"h6\", your files will be split at those headers. Both the standard `atx` and `Setext` formats are supported -- the former uses 1 to 6 hashes (`# ` to `###### `) at the start for \u0026lt;h1\u0026gt; to \u0026lt;h6\u0026gt;, while the later uses equals-underscores for \u0026lt;h1\u0026gt; and dash-underscores for \u0026lt;h2\u0026gt;\n\nFor example, if your separator is `\"h1\"`:\n\n```markdown\n# Introduction\nThis is a page.\n\nDiscussion\n==========\nThis is another page\n\n## Point 1\nThis is not.\n\nPoint 2\n-------\nNeither is this\n\n\u003ch1\u003eConclusion\u003c/h1\u003e\nBut this is.\n```\n\nAt this time, you'll need at least 4 dashes for Setext-style \u0026lt;h2\u0026gt;. Note that Setext only supports \u0026lt;h1\u0026gt; and \u0026lt;h2\u0026gt;.\n\n### Page headers and footers\n\nAnything above your configured `header` string will appear at the top of the generated pages. Likewise, anything after your `footer` string will appear at the bottom.\n\n```markdown\nThis is the header\n\u003c!--page_header--\u003e\n\nThis is a page.\n\u003c!--page--\u003e\nThis is another page.\n\n\u003c!--page_footer--\u003e\nThis is the footer.\n```\n\nIf you split your links like so:\n\n```markdown\nThis is a [link].\n\n[link]: https://example.com\n```\n\nmake sure you put these referenced link definitions below the `footer` so that references to them will work across pages.\n\n### Minimum page length\n\nYou may set the minimum length (in characters) using the `minimum` property in `_config.yml` or your front-matter. Should a particular section be too short, the next section will be merged in, and so on until the minimum is reached or there are no more pages.\n\nNote that this length includes markup, not just the actual displayed text, so you may want to take that into consideration. A minimum of 1000 to 2000 should work well.\n\n## Paginator Properties/Fields\n\nThese properties/fields are available to your layouts and content via the `paginator` object, e.g. `{{ paginator.page }}`.\n\n\n| Field                | Aliases         | Description                         |\n|----------------------|-----------------|-------------------------------------|\n| `first_page`         |                 | First page number, i.e. 1           |\n| `first_page_path`    | `first_path`    | Relative URL to the first page      |\n| `next_page`          |                 | Next page number                    |\n| `next_page_path`     | `next_path`     | Relative URL to the next page       |\n| `previous_page`      | `prev_page`     | Previous page number                |\n| `previous_page_path` | `previous_path`\u003cbr/\u003e`prev_path` | Relative URL to the previous page\n| `last_page`          |                 | Last page number                    |\n| `last_page_path`     | `last_path`     | Relative URL to the last page       |\n| `page`               | `page_num`      | Current page number                 |\n| `page_path`          |                 | Path to the current page            |\n| `page_trail`         |                 | Page trail, see [below](#pagination-trails)    |\n| `total_pages`        | `pages`         | Total number of pages               |\n|                      |                 |                                     |\n| `single_page`        | `view_all`      | Path to the original/full page      |\n| `seo`                |                 | HTML header tags for SEO, see [below](#search-engine-optimization-seo)\n| `toc`                |                 | Table Of Contents generator, see [below](#table-of-contents-toc)\n|                      |                 |                                     |\n| `section`            |                 | Text of the first header (\u0026lt;h1\u0026gt; etc.) on this page\n| `previous_section`   | `prev_section`  | Ditto for the previous page         |\n| `next_section`       |                 | Ditto for the next page             |\n| `section_id`         |                 | The header id (`\u003ca name\u003e`) of this section\n|                      |                 |                                     |\n| `paginated`          | `activated`     | `true` if this is a partial page    |\n| `has_next`           |                 | `true` if there is a next page      |\n| `has_previous`       | `has_prev`      | `true` if there is a previous page  |\n| `is_first`           |                 | `true` if this is the first page    |\n| `is_last`            |                 | `true` if this is the last page     |\n| `next_is_last`       |                 | `true` if this page is next-to-last |\n| `previous_is_first`  | `prev_is_first` | `true` if this is the second page   |\n\n### site.baseurl\n\nBy default, JPC automatically prepends your `site.baseurl` to generated paths so you don't have to do it yourself. If you don't like this behavior, set `prepend_baseurl: false` in your configuration.\n\n## Page/Post properties\n\nThese properties are automatically set for pages and other content that have been processed, e.g `{{ post.autogen }}`\n\n| Field                | Description\n|----------------------|----------------------------------------------------------------------\n| `permalink`          | Relative path of the current page\n|                      |\n| `hidden`             | `true` for all pages (including the single-page view) except the first page\n| `tag`, `tags`        | `nil` for all except the first page\n| `category`, `categories` | `nil` for all except the first page\n|                      |\n| `autogen`            | \"jekyll-paginate-content\" for all pages\n| `pagination_info`    | `.curr_page` = current page number\u003cbr/\u003e`.total_pages` = total number of pages\u003cbr/\u003e`.type` = \"first\", \"part\", \"last\", or \"single\"\u003cbr/\u003e`.id` = a string which is the same for all related pages\n\nThe tags, categories, and `hidden` are set up this way to avoid duplicate counts and having the parts show up in e.g. your tag index listings. You may override this behavior as discussed [below](#overriding-and-restoring-properties).\n\n### Setting custom properties\n\n`paginate_content` has a `properties` option:\n\n```yaml\npaginate_content:\n  properties:\n    all:\n      field1: value1\n      # ...etc...\n    first:\n      field2: value2\n      # ...etc...\n    part:\n      field3: value3\n      # ...etc...\n    last:\n      field4: value4\n      # ...etc...\n    single:\n      field5: value5\n      # ...etc...\n```\n\nwhere the properties/fields listed under `all` will be set for all pages, `first` properties for the first page (possibly overriding values in `all`), etc.\n\n**Example:** To help with your layouts, you may want to set a property for the single-page view, say, activating comments:\n\n```yaml\npaginate_content:\n  properties:\n    single:\n      comments: true\n```\n\nIn your layout, you'd use something like\n\n```liquid\n{% if post.comments %}\n   \u003c!-- Disqus section --\u003e\n{% endif %}\n```\n\nThe single-page view would then show the [Disqus](https://disqus.com/) comments section. \n\n### Overriding and restoring properties\n\nYou can set almost any front-matter property via the `properties` section, except for `title`, `date`, `permalink`, and `pagination_info`. Use with caution.\n\n#### Special values\n\nYou may use the following values for properties:\n\n| Value | Meaning\n|-------|--------------------------------------\n| `~`   | `nil` (essentially disabling the property)\n| `$`   | The original value of the property\n| `$.property` | The original value of the specified `property`\n| `/`   | Totally remove this property\n \n### Default properties\n\nFor reference, the default properties effectively map out to:\n\n```yaml\n  properties:\n    all:\n      autogen: 'jekyll-paginate-content'\n      hidden: true\n      tag: ~\n      tags: ~\n      category: ~\n      categories: ~\n      pagination_info:\n        curr_page: (a number)\n        total_pages:  (a number)\n        id: '(a string)'\n\n    first:\n      hidden: false\n      tag: $\n      tags: $\n      category: $\n      categories: $\n      pagination_info:\n        type: 'first'\n\n    part:\n      pagination_info:\n        type: 'part'\n\n    last:\n      pagination_info:\n        type: 'last'\n\n    single:\n      pagination_info:\n        curr_page: /\n        total_pages: /\n        type: 'single'\n```\n\n### Example: blog\n\nThe author's `_config.yml` has the following:\n\n```yaml\n  properties:\n    all:\n      comments: false\n      share: false\n      x_title: $.title\n\n    #first:\n      # keeps original tags and categories\n\n    part:\n      x_tags: []\n      x_cats: []\n\n    last:\n      comments: true\n      share: true\n      x_tags: $.tags\n      x_cats: $.categories\n\n    single:\n      comments: true\n      share: true\n      x_tags: $.tags\n      x_cats: $.categories\n```\n\n`x_tags` and `x_cats` are used in this case to store the original tags and categories for generating a list of related posts only for last pages or single-page views. `comments` and `share` are likewise used to turn on the sections for comments and social media sharing for these pages.\n\n`x_title` saves the original title for use in social media sharing. The example below also does something similar for the URL to be shared:\n\n```liquid\n{% if page.x_title %}\n  {% assign share_title = page.x_title %}\n{% else %}\n  {% assign share_title = page.title %}\n{% endif %}\n\n{% if paginator.first_path %}\n  {% assign share_url = paginator.first_path %}\n{% else %}\n  {% assign share_url = page.url %}\n{% endif %}\n```\n\n### Example: slides/presentation\n\nJPC can be used to generate slides as well as a detailed document from the same source Markdown, i.e.\n\n```liquid\n{% if paginator.paginated %}\n  // Content that only shows up in the slides\n{% else %}\n  // Content that only shows up in the single/details page.\n{% endif %}\n```\n\nOr alternatively,\n\n```liquid\n{% if paginator.paginated %}\n  // Content that only shows up in the slides\n{% endif %}\n```\n\nand\n\n```liquid\n{% unless paginator.paginated %}\n  // Content that only shows up in the single/details page.\n{% endif %}\n```\n\nHere's an example configuration:\n\n```yaml\n  properties:\n    all:\n      layout: slides\n    single:\n      layout: $\n```\n\nThis makes all pages except the single-page view use the `slides` layout. The latter will use the original layout.\n\n#### Last slide\n\nWhen using JPC to generate slides, you may use `_last_` as the title for the last slide (usually a \"thank you\" or contact info slide). It will be removed and hidden from the TOC.\n\nThe [demos](#demos) include a sample presentation.\n\n## Pagination trails\n\nYou use `paginator.page_trail` to create a pager that will allow your readers to move from page to page. It is set up as follows:\n\n```yaml\npaginate_content:\n  trail:\n    before: 2\n    after: 2\n```\n\n`before` refers to the number of page links you want to appear before the current page, as much as possible. Similarly, `after` is the number of page links after the current page. So, in the above example, you have 2 before + 1 current + 2 after = 5 links to pages in your trail \"window\".\n\nIf you don't specify the `trail` properties, or set `before` and `after` to 0, all page links will be returned.\n\nLet's say your document has 7 pages, and you have a `trail` as above. The pager would look something like this as you go from page to page:\n\n\u003cpre\u003e\u003cstrong\u003e\u0026laquo; \u003c1\u003e [2] [3] [4] [5] \u0026raquo;\n\u0026laquo; [1] \u003c2\u003e [3] [4] [5] \u0026raquo;\n\u0026laquo; [1] [2] \u003c3\u003e [4] [5] \u0026raquo;\n\u0026laquo; [2] [3] \u003c4\u003e [5] [6] \u0026raquo;\n\u0026laquo; [3] [4] \u003c5\u003e [6] [7] \u0026raquo;\n\u0026laquo; [3] [4] [5] \u003c6\u003e [7] \u0026raquo;\n\u0026laquo; [3] [4] [5] [6] \u003c7\u003e \u0026raquo;\n\u003c/strong\u003e\u003c/pre\u003e\n\n### Usage\n\n`paginator.page_trail` has the following fields:\n\n| Field   | Description\n|---------|-------------------------------------- \n| `num`   | The page number\n| `path`  | The path to the page\n| `title` | The title of the page\n\nHere is an example adapted from [JPv2's documentation](https://github.com/sverrirs/jekyll-paginate-v2/blob/master/README-GENERATOR.md#creating-pagination-trails). Note that you don't need to prepend `site.baseurl` to `trail.path` as it is automatically added in by JPC [by default](#sitebaseurl).\n\n```liquid\n{% if paginator.page_trail %}\n  \u003cul class=\"pager\"\u003e\n  {% for trail in paginator.page_trail %}\n    \u003cli {% if page.url == trail.path %}class=\"selected\"{% endif %}\u003e\n        \u003ca href=\"{{ trail.path }}\" title=\"{{ trail.title }}\"\u003e{{ trail.num }}\u003c/a\u003e\n    \u003c/li\u003e\n  {% endfor %}\n  \u003c/ul\u003e\n{% endif %}\n```\n\nIts [accompanying style](https://github.com/sverrirs/jekyll-paginate-v2/blob/master/examples/03-tags/_layouts/home.html):\n\n```html\n\u003cstyle\u003e\n  ul.pager { text-align: center; list-style: none; }\n  ul.pager li {display: inline;border: 1px solid black; padding: 10px; margin: 5px;}\n  .selected { background-color: magenta; }\n\u003c/style\u003e\n```\n\nYou'll end up with something like this, for page 4:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/ibrado/jekyll-paginate-content/master/res/jpv2-trail.png\" /\u003e\n\u003c/p\u003e\n\nThe author's own pager is a little more involved and uses some convenience fields and aliases:\n\n```liquid\n{% if paginator.page_trail %}\n  \u003cdiv class=\"pager\"\u003e\n    {% if paginator.is_first %}\n      \u003cspan class=\"pager-inactive\"\u003e\u003ci class=\"fa fa-fast-backward\" aria-hidden=\"true\"\u003e\u003c/i\u003e\u003c/span\u003e\n      \u003cspan class=\"pager-inactive\"\u003e\u003ci class=\"fa fa-backward\" aria-hidden=\"true\"\u003e\u003c/i\u003e\u003c/span\u003e\n    {% else %}\n      \u003ca href=\"{{ paginator.first_path }}\"\u003e\u003ci class=\"fa fa-fast-backward\" aria-hidden=\"true\"\u003e\u003c/i\u003e\u003c/a\u003e\n      \u003ca href=\"{{ paginator.previous_path }}\"\u003e\u003ci class=\"fa fa-backward\" aria-hidden=\"true\"\u003e\u003c/i\u003e\u003c/a\u003e\n    {% endif %} \n\n    {% for p in paginator.page_trail %}\n      {% if p.num == paginator.page %}\n        {{ p.num }} \n      {% else %}\n        \u003ca href=\"{{ p.path }}\" data-toggle=\"tooltip\" data-placement=\"top\" title=\"{{ p.title }}\"\u003e{{ p.num }}\u003c/a\u003e\n      {% endif %}\n    {% endfor %}\n\n    {% if paginator.is_last %}\n      \u003cspan class=\"pager-inactive\"\u003e\u003ci class=\"fa fa-forward\" aria-hidden=\"true\"\u003e\u003c/i\u003e\u003c/span\u003e\n      \u003cspan class=\"pager-inactive\"\u003e\u003ci class=\"fa fa-fast-forward\" aria-hidden=\"true\"\u003e\u003c/i\u003e\u003c/span\u003e\n    {% else %}\n      \u003ca href=\"{{ paginator.next_path }}\"\u003e\u003ci class=\"fa fa-forward\" aria-hidden=\"true\"\u003e\u003c/i\u003e\u003c/a\u003e\n      \u003ca href=\"{{ paginator.last_path }}\"\u003e\u003ci class=\"fa fa-fast-forward\" aria-hidden=\"true\"\u003e\u003c/i\u003e\u003c/a\u003e\n    {% endif %} \n  \u003c/div\u003e\n{% endif %}\n```\n\nThis results in a pager that looks like this:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/ibrado/jekyll-paginate-content/master/res/ajni-trail-p1.png\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/ibrado/jekyll-paginate-content/master/res/ajni-trail-p4.png\" /\u003e\n\u003c/p\u003e\n\n### Page flipper\n\nYou may also want to add a page \"flipper\" that uses section names:\n\n```liquid\n\u003c!--page_footer--\u003e\n\u003cdiv\u003e\n  {% if paginator.previous_section %}\n    \u0026laquo; \u003ca href=\"{{ paginator.previous_path }}\"\u003e{{ paginator.previous_section }}\u003c/a\u003e\n  {% endif %}\n  {% if paginator.previous_section and paginator.next_section %} | {% endif %}\n  {% if paginator.next_section %}\n    \u003ca href=\"{{ paginator.next_path }}\"\u003e{{ paginator.next_section }}\u003c/a\u003e \u0026raquo;\n  {% endif %}\n\u003c/div\u003e\n```\n\nShould there be no available section name, \"Untitled\" will be returned. You can then handle it like so:\n\n```liquid\n{% if paginator.previous_section == \"Untitled\" %}\n  Previous\n{% else %}\n  {{ paginator.previous_section }}\n{% endif %}\n```\n\nOf course, you always have the option of adding some navigational cues to your content:\n\n```liquid\n{% if paginator.paginated %}\n  \u003ca href=\"{{ paginator.next_page_path }}\"\u003eOn to the next chapter...\u003c/a\u003e\n{% endif %}\n```\n\nThis text will not appear in the single-page view.\n\n## Table Of Contents (TOC)\n\nJPC automatically generates a Table of Contents for you. To use this from within your content, simply insert the following:\n\n```liquid\n  {{ paginator.toc.simple }}\n```\n\nIf you want to use this from an HTML layout, e.g. an included `sidebar.html`:\n\n```liquid\n  {{ paginator.toc.simple | markdownify }}\n```\n\nThe difference between this and the one built into [kramdown](https://kramdown.gettalong.org/), the default Jekyll Markdown engine, is that it is aware that content may be split across several pages now, and adjusts links depending on the current page.\n\n\u003e The reason `paginator.toc.simple` is used vs just `paginator.toc` is to allow for further TOC features in the future.\n\n### Excluding sections\n\nShould you want some sections excluded from the Table Of Contents, add them to the `toc_exclude` option in your site configuration or content front-matter:\n\n```yaml\npaginate_content:\n  toc_exclude: \"Table Of Contents\"\n```\nor\n\n```yaml\npaginate_content:\n  toc_exclude: \n    - \"Table Of Contents\"\n    - \"Shy Section\"\n```\n\nThe generated section ids follow the usual convention:\n\n1. Convert the section name to lowercase\n1. Remove all punctuation\n1. Convert multiple spaces to a single space\n1. Convert spaces to dashes\n1. If that id already exists, add \"-1\", \"-2\", etc. until the id is unique\n\n## Search Engine Optimization (SEO)\n\nNow that your site features split pages (*finally!*), how do you optimize it for search engines?\n\n`paginator.seo` has the following fields:\n\n| Field       | Description\n|-------------|-------------------------------------- \n| `canonical` | HTML `link rel` of the canonical URL (primary page for search results)\n| `prev`      | Ditto for the previous page, if applicable\n| `next`      | Ditto for the next page, if applicable\n| `links`     | All of the above, combined\n\nYou could simply add the following somewhere inside the \u003ctt\u003e\u0026lt;head\u0026gt;\u003c/tt\u003e of your document:\n\n```liquid\n{{ paginator.seo.links }}\n```\n\nIt will produce up to three lines, like so (assuming you are on page 5):\n\n```html\n  \u003clink rel=\"canonical\" href=\"https://example.com/2017/12/my-post/view-all/\" /\u003e\n  \u003clink rel=\"prev\" href=\"https://example.com/2017/12/my-post/4/\" /\u003e\n  \u003clink rel=\"next\" href=\"https://example.com/2017/12/my-post/6/\" /\u003e\n```\n\n`rel=\"prev\"` and/or `rel=\"next\"` will not be included if there is no previous and/or next page, respectively. If you don't want to set canonical to the single-view page, just set `seo_canonical` in your `_config.yml` to `false`.\n\n### Unified approach\n\nIt would be better to use the following approach, though:\n\n```liquid\n{% unless paginator %}\n  \u003clink rel=\"canonical\" href=\"{{ site.canonical }}{{ site.baseurl }}{{ page.url }}\" /\u003e\n{% endunless %}\n{% if paginator.seo.links %}\n{{ paginator.seo.links }}\n{% else %}\n  {% if paginator.previous_page_path %}\n  \u003clink rel=\"prev\" href=\"{{ site.url }}{{ site.baseurl }}{{ paginator.previous_page_path }}\" /\u003e\n  {% endif %}\n  {% if paginator.next_page_path %}\n  \u003clink rel=\"next\" href=\"{{ site.url }}{{ site.baseurl }}{{ paginator.next_page_path }}\" /\u003e\n  {% endif %}\n{% endif %}\n```\n\nThis way it works with JPv2, JPC, and with no paginator active.\n\nWhat about `canonical` for JPv2-generated pages? Unless you have a \"view-all\" page that includes all your unpaginated posts and you want search engines to use that possibly huge page as the primary search result, it is probably best to just not put a `canonical` link at all.\n\n## Demos\n\n1. TL;DR demos: [manual](https://ibrado.org/demos/jpc-3page-manual/), [automatic](https://ibrado.org/demos/jpc-3page-auto/)\n1. Simple example as a [post](https://ibrado.org/2017/12/jpc-demo-post/), as an item in a [collection](https://ibrado.org/demos/jpc/), and as a [page](https://ibrado.org/jpc-demo/).\n1. [This README](https://ibrado.org/jpc/readme/), autopaginated\n1. [Simple Slides in Jekyll](https://ibrado.org/jpc/slides/)\n\n## Limitations\n\n1. Some link/anchor formats may not be supported yet; inform author, please.\n1. The Setext mode, i.e. underscoring header names with equal signs (\u003ctt\u003e\u0026lt;h1\u0026gt;\u003c/tt\u003e) or dashes (\u003ctt\u003e\u0026lt;h2\u0026gt;\u003c/tt\u003e), needs to have at least 4 dashes for \u003ctt\u003e\u0026lt;h2\u0026gt;\u003c/tt\u003e.\n\n## Contributing\n\n1. Fork this project: [https://github.com/ibrado/jekyll-paginate-content/fork](https://github.com/ibrado/jekyll-paginate-content/fork)\n1. Clone it (`git clone git://github.com/your_user_name/jekyll-paginate-content.git`)\n1. `cd jekyll-paginate-content`\n1. Create a new branch (e.g. `git checkout -b my-bug-fix`)\n1. Make your changes\n1. Commit your changes (`git commit -m \"Bug fix\"`)\n1. Build it (`gem build jekyll-paginate-content.gemspec`)\n1. Install and test it (`gem install ./jekyll-paginate-content-*.gem`)\n1. Repeat from step 5 as necessary\n1. Push the branch (`git push -u origin my-bug-fix`)\n1. Create a Pull Request, making sure to select the proper branch, e.g. `my-bug-fix` (via https://github.com/your_user_name/jekyll-paginate-content)\n\nBug reports and pull requests are welcome on GitHub at [https://github.com/ibrado/jekyll-paginate-content](https://github.com/ibrado/jekyll-paginate-content). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n\n## Code of Conduct\nEveryone interacting in the Jekyll::Paginate::Content project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/ibrado/jekyll-paginate-content/blob/master/CODE_OF_CONDUCT.md).\n\n## Also by the Author\n\n[Jekyll::Stickyposts](https://github.com/ibrado/jekyll-stickyposts) - Move/pin posts tagged `sticky: true` before all others. Sorting on custom fields supported; collection and paginator friendly.\n\n[Jekyll::Tweetsert](https://github.com/ibrado/jekyll-tweetsert) - Turn tweets into Jekyll posts. Multiple timelines, filters, hashtags, automatic category/tags, and more!\n\n[Jekyll::ViewSource](https://github.com/ibrado/jekyll-viewsource) - Generate pretty or plain HTML and/or Markdown source code pages.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fibrado%2Fjekyll-paginate-content","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fibrado%2Fjekyll-paginate-content","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fibrado%2Fjekyll-paginate-content/lists"}