keelapps/Sort Pages for Confluence/Documentation

Documentation

Sort Pages keeps a Confluence page tree in the order you choose. You set a rule once — on a page, a folder or a whole space — and pages that are created, renamed, moved, copied or restored later fall into place by themselves. Only the order in the page tree changes: no page is edited, and no version is created.

Where Sort Pages lives

• On any page: ••• (More actions) → Apps → Sort child pages — preview, sort once, or keep the pages under that page sorted from now on. Anyone who can edit the page can use it.
• Space settings → Integrations → Sort Pages — every rule in the space, with Sort now, Pause, Restore and Remove, a form for whole-space rules, and the activity log. Space administrators only.

Sorting the pages under one page

Open Sort child pages from the page whose children you want in order. Choose an order, and optionally pages to keep first or last, then:

• Preview lists the children in their new order and marks each one moves or in place, with where it sits now. Nothing changes.
• Sort once puts the children in that order and stops there. Pages added later land wherever Confluence puts them.
• Keep sorted saves a rule on the page. Choose whether it covers only the pages directly under it, or every level below it.

The panel says whether the page already has a rule, or is covered by a rule set higher up the tree — and on which page that rule lives.

The orders

Natural number order can be switched off. Two titles that differ only in case are ordered by case, and two identical titles by page id, so the order is the same every time the sort runs. Always first and Always last pin chosen pages to the top and bottom of the list in the order you pick them; everything else is sorted between them.

Rules, and how they combine

A rule is set on one page or folder and reaches either its direct children or every level below it. A whole-space rule is a rule on the space's home page that reaches every level below: that is everything in the page tree.

When more than one rule could apply to a list, the nearest one wins: a rule on the list's own parent, otherwise the closest rule above it that reaches every level. So a space sorted A to Z can keep its release notes newest first, and a hand-arranged onboarding section can be marked Leave as arranged and left alone. A page carries at most one rule; saving a rule on a page that has one changes it.

The top level of a space — pages with no parent at all — is not sorted. Confluence warns that positioning a page against a top-level page can take it out of the page tree, and in a normal space everything lives under the home page anyway.

When sorting happens

• On change. Confluence tells the app when a page or folder is created, renamed, moved, copied, restored, unarchived or published, and when someone reorders a list by hand. The app waits about twenty seconds so a burst of changes — an import, a page and its first edits — becomes one sort, then puts the affected list in order. Most changes are in place within a minute.
• Weekly. Once a week each rule is checked from end to end, which catches anything a change notification missed and pages that were out of order before the rule existed.
• On request. Sort now in space settings runs that check immediately.

Each sort moves as few pages as possible: the pages already in the right relative order stay where they are, and only the rest are moved, one at a time. One new page under a sorted page costs one move. Before moving anything the app re-reads the list, and after moving it reads the list again to confirm the result.

Restoring the original order

The first time Sort Pages reorders a list, it records the order it found. From the page (Restore the earlier order) or from space settings (Restore earlier order on a rule, which covers every list that rule has reordered), the app puts those lists back. Pages created since the snapshot go at the end.

Restoring also stops the sorting, or the next change would sort the list straight back: the page's own rule is paused, or — if the list was covered by a rule higher up — a Leave as arranged exception is added on that page. Resume or remove it when you want sorting back.

What stays where it is

• Pages the app is not allowed to move — restricted so that the app cannot see or edit them — keep their position, and the rest of the list is sorted around them. The preview marks them, and the activity log records it.
• Pages Confluence refuses to move — for example a page whose own subtree is very large — are treated the same way after a second refusal.
• Lists of more than 2,000 items are reported as too large rather than half sorted.
• Whiteboards, databases and smart links in a list are sorted with the pages when Confluence lets the app move them, and kept in place when it does not.

The activity log

Space settings list the sixty most recent events in the space: every sort that moved something (and how many pages, and whether a change set it off), every restore, rule added, changed, paused or removed, weekly checks that found work to do, and any sort that could not finish, with the reason. A check that found everything in order is not recorded.

Who can do what

• Anyone who can view a page can open Sort child pages and preview.
• Anyone who can edit a page can sort its children, keep them sorted, or restore them. The check is made as the person clicking, every time.
• Space administrators manage the space's rules in space settings, including whole-space rules.

The moves themselves are made by the app, so a sort still completes when the person who set the rule is not around — which is also why the permission check happens before a rule is saved, not after. It also means a rule positions every child page the app can move, including one that some of the parent's editors could not edit themselves: only its place among its siblings changes, never its content or its restrictions. A page restricted from the app stays where it is.

API points and pacing

Confluence gives each app one hourly allowance of API requests, shared by every site that has the app installed. Sort Pages keeps each site well inside its share: an edit that did not change a title costs at most a couple of reads, and a large first sort that would use too much of the hour pauses and resumes in the next one instead of running over.

Permissions the app requests

There is no permissions.external block: the app cannot make an outbound call even if it tried to, which Atlassian enforces at the platform level. The app never asks Confluence for the content of a page.

Not in this release

• Recently updated first. Deliberately: it would rearrange the page tree on every edit.
• Blog posts. They have no page tree to sort.
• The top level of a space. See rules.
• Custom orders by label or page property.

Support

Questions, bug reports and feature requests: raise a support request. Security issues: report privately.