2.2 – Sorting

What gets sorted is always the children of one folder among themselves. There are three methods:

options:
  sort: manual        # manual | alphabetical | date
  sortDirection: asc  # asc | desc
  foldersFirst: first # first | last | mixed

Folders first

Before any method comes foldersFirst: first puts folders before pages, last after them, mixed sorts both together. Within the folders and within the pages the chosen method then applies.

manual — the cascade

The default. Four stages, each one only decides where the previous one was tied:

Stage	Source	Example
1	the order list in the configuration	order: { docs: [intro, setup] }
2	navOrder in the frontmatter	navOrder: 10
3	the number in front of the file or directory name	02 Setup.md
4	the title	Setup

Whoever has no value at a stage comes after everyone who has one. A page with navOrder therefore comes before every page without — whatever number the other carries in its file name.

Without order, navOrder and numbers, the cascade gives an alphabetical order.

The order list

The order in one place instead of spread across many frontmatter blocks:

options:
  order:
    "": [docs, blog, about]      # the root
    docs: [intro, setup, faq]

• The key is the folder path; "" is the root. docs, docs/, docs/index and docs.md mean the same.
• An entry is the last part of the slug (intro) or the file or directory name (01 Intro); upper and lower case do not matter.
• Whatever is not in the list follows after it, ordered by stages 2 to 4.
• An entry that does not exist in the folder is reported once by the build (9.2) — usually a typo or a renamed file.

foldersFirst comes before the list

With the default foldersFirst: first, folders come before pages even if the list says otherwise. about in the example above is a page and therefore ends up after docs and blog, wherever it is in the list. For the list alone to count, add foldersFirst: mixed.

navOrder

A number, smaller first. Decimals and negative values work, as does a number in quotes. In an index.md, navOrder sets the position of the folder among its siblings. Tip: use steps of ten, so something fits in between later.

Numbers

01 Intro, 02-setup, 3_faq, 4. Appendix — a number at the start, followed by -, _, . or a space. The number is compared as a number, 10 comes after 9. Whether it stays visible in the title is decided by stripNumericPrefix (2.1).

alphabetical

The title only. Compared naturally — Part 2 before Part 10 — and regardless of case or accents.

The language decides the order of letters. The plugin sorts with the locale from the Quartz configuration: with de-DE, Ärger sits next to Apfel; with sv-SE, after Zebra. That way every machine that builds the site sorts the same. On a multilingual site every tree sorts by its language: with the site’s locale when it is the same language, otherwise with the language code (8.3).

date

options:
  sort: date
  dateField: created    # created | modified | published
  sortDirection: desc   # newest first

The dates come from Quartz’s created-modified-date plugin; its configuration decides which date a page has. Pages without a date come last; with equal dates the title decides.

The direction

sortDirection: desc reverses every stage, including the title. Missing values still stay at the end: a blog with sort: date and desc lists undated posts after the dated ones, not before.

Two navigations, two orders

Every entry sorts on its own. A pager through the posts by date and a sidebar in manual order get along — they then read two differently sorted trees (1.3).