Add a pagination config option for docs.

[homotechsual]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Description

Add a config option for docs to enable/disable pagination:

Idea 1 - Global:

docusaurus.config.js

docs: {
    path: 'docs/gettingstarted',
    routeBasePath: 'docs/gettingstarted',
    sidebarPath: require.resolve('./sidebars.js'),
    // Please change this to your repo.
    // Remove this to remove the "edit this page" links.
    editUrl: 'https://github.com/facebook/docusaurus/tree/main',
    showLastUpdateAuthor: true,
    showLastUpdateTime: true,
    +pagination: false,
},

Idea 2 - Per Page:

docs/introduction.md

---
description: Docusaurus was designed from the ground up to be easily installed and used to get your website up and running quickly.
slug: /
+pagination: false
---

Potentially related: https://docusaurus.io/feature-requests/p/remove-pagination-from-autogenerated-category-page

Has this been requested on Canny?

No response

Motivation

This discussion sparked the idea: https://discord.com/channels/398180168688074762/867060369087922187/989237092724932668 I feel, broadly that more configuration of this nature with low maintenance burden and simple implementation benefits all users of docusaurus by increasing overall flexibility.

API design

I prefer option 1 above as I don't feel implementing this "per page" is as useful. So this would be controled by users in their doc config in docusaurus.config.js.

Have you tried building it?

No

Self-service

• I'd be willing to contribute this feature to Docusaurus myself.

[Josh-Cena]

Makes sense to me at first glance. I'm a bit ambivalent on this, since a no-API solution is to swizzle @theme/DocItem/Paginator and make it return null instead. On one hand, swizzling doesn't work well with multi-instance. On the other hand, this option would probably require putting this in global data, which I don't like. Speaking of pagination: false, we already have pagination_next: null and pagination_prev: null.

[LauraLangdon]

Came here seeking exactly such a solution! Our section headings are more like trees, where there isn't a sequential order between the nodes, so from one page there might be several pages that would be equally good candidates as "next" pages. So we'd prefer to select and link such pages ourselves rather than have buttons auto-generated. Like a Choose Your Own Adventure kind of scenario, rather than a strictly linear progression.

Would be nice to not need to add pagination_next: null and pagination_prev: null in the front matter of each page. Not that that's a super heavy lift, of course, but slightly usboptimal.

[slorber]

It looks to me that people may be looking for different things here:

• On Canny, the goal seems to be to disable pagination, but only for generated index categories: https://docusaurus.io/feature-requests/p/remove-pagination-from-autogenerated-category-page
• Here it's suggested to disable pagination for a whole docs plugin instance

In the short term, I think we could add paginationNext and paginationPrev options to Category generated index config.

This would be consistent with what we already provide for Docs.

Now, you'd be able to configure/disable pagination with a lot of flexibility for both docs + category generated index.

---

I agree that it is not the most convenient API to disable this globally though, in which case other solutions like swizzling are better alternatives.

Makes sense to me at first glance. I'm a bit ambivalent on this, since a no-API solution is to swizzle @theme/DocItem/Paginator and make it return null instead. On one hand, swizzling doesn't work well with multi-instance.

Not yet documented, but this could be handled conditionally with useRouteContext().plugin.name === "xyz"

---

Would be nice to not need to add pagination_next: null and pagination_prev: null in the front matter of each page.

Note we also want to introduce some kind of generic createFrontMatter() hook (#5568)

It could also be used to implement your own disable_pagination: true or whatever custom frontmatter API you want to use:

function createFrontMatter({ frontMatter }) {
  if (frontMatter.disable_pagination) {
    return { ...frontMatter, pagination_next: null, pagination_prev: null };
  }
}

Or simply disable pagination for all docs by default, with possibility to override it on a per-doc basis:

function createFrontMatter({ frontMatter }) {
  return {
    ...frontMatter,
    pagination_next: frontMatter.pagination_next ?? null,
    pagination_prev: frontMatter.pagination_prev ?? null
  };
}

Unfortunately, it wouldn't affect the pagination of generated category index when not linking to any doc (as there's no doc, there's no frontMatter).

---

Considering the different use-cases of users, and the availability of good-enough workarounds, I'd like to not rush on implementing a new API for this.

Please give more details of your use-cases.

Ideally, implement workarounds in userland first, deploy them, and show us the production doc site so that we can understand better the patterns, and how to design this feature with every use-case in mind.

If your site is not public, at least provide screenshots clearly showing the use-case, including the display of real content that makes it clear why pagination is unwanted.

Why? Because we try to provide flexible low-level primitives first (like createFrontMatter() and useRouteContext) instead of providing high-level convenient APIs (and figuring out later we were wrong in our assumptions). Similarly to how the web platform is designed over time (https://extensiblewebmanifesto.org/)

[AlbertVilaCalvo]

Please give more details of your use-cases.

@slorber I'm very interested in having a global option to disable pagination for all docs (including generated index pages).

I'm using Docusaurus to build my personal Wiki (knowledge base):

• Site: https://albert.wiki
• Source code: https://github.com/AlbertVilaCalvo/Wiki

I have many documents, all of them with Previous and Next links that I don't need, since the documents are not meant to be read linearly, but instead hold independent content.

I could add pagination_next: null + pagination_prev: null to all docs to get rid of the links, but this would not work for generated index pages. Also, having pagination_next: null + pagination_prev: null on all docs is a lot of clutter.

In my opinion this global option should only affect the docs, not the blog.

[alexfornuto]

Hi friends! This thread has been silent for a year now, so lemme ask: what are the odds that a global pagination disable option is on the horizon?

[slorber]

As soon as v3 is out (soon) I'll work on createFrontMatter #5568

This unlocks a ton of use cases so it's a top priority for me.

To disable pagination, it could look like this:

const docsPluginOptions = {
  // ... other options
  createFrontMatter: ({ frontMatter }) => {
    return {
      ...frontMatter,
      pagination_next: frontMatter.pagination_next ?? null,
      pagination_prev: frontMatter.pagination_prev ?? null
    };
  }
}

It is not as simple as pagination: false but it has the benefit of being more powerful and it solves other use cases as well.

[alexfornuto]

Consider my breath bated.

[AlbertVilaCalvo]

I've been able to remove the 'Previous' and 'Next' links by adding this code to docusaurus.config.ts:

const config: Config = {
  // ...
  markdown: {
    parseFrontMatter: async (params) => {
      // Reuse the default parser
      const result = await params.defaultParseFrontMatter(params)
      result.frontMatter.pagination_prev = null
      result.frontMatter.pagination_next = null
      return result
    },
  },
}

See the documentation for more:

https://docusaurus.io/docs/markdown-features#front-matter
https://docusaurus.io/docs/api/docusaurus-config#markdown

Note that this API was added in version 3.1.

@slorber I believe we can close this issue.

[slorber]

Yes thanks, this can be closed now.

The alternative is to create your own front matter "shortcut" to disable both next/prev buttons, as documented here: https://docusaurus.io/docs/markdown-features#front-matter

Similarly, you could also make the pagination "opt-in", ie use a front matter boolean to turn it on only on certain pages.

This API is a bit low-level but it's quite flexible and gets the job done.