Sort folder contents by a custom field

What you'll see

You want the documents inside a published folder to display in a deliberate order — a manual sequence, a priority number, or a category — instead of alphabetically by filename. You add a sort field (for example Order) to the documents, but the published folder still lists them by name — or it lists them in the wrong order, 1, 10, 11, 2, 3 instead of 1, 2, 3 … 10, 11.

What's actually happening

A published folder's listing is driven by its folder properties — the .docly file that sits inside the folder (schema Published folder or Folder). Two properties control the columns and their sorting:

• SpecifyCustomColumns — set to true to replace the default listing with your own columns.
• CustomColumns — an array of column definitions.

Each column is an object with four fields:

• Title — the column header shown in the listing.
• Formula — a JavaScript expression evaluated once per document in the folder. Bare identifiers resolve to fields in that document's Document block, so Order reads the document's Order field, parseInt(Order) reads it as a number, and helpers such as Thumb(File) are available too.
• Sorting — "Sortable" makes the column header clickable to sort by; "No" shows the value as a plain, non-sortable column.
• ROWID — a unique id for the column row.

The mechanism has two halves that must agree: the documents carry the value to sort on (a field in their schema), and the folder properties declare a column whose Formula reads that field. If the formula names a field the documents don't have, the column comes up empty and nothing sorts. If the field is text and you don't wrap it in parseInt(), it sorts lexically — "10" lands before "2".

What to do

1. Give the documents a field to sort on. The documents in the folder need a field in their schema to hold the sort value — typically a number field named Order or SortOrder. Set a value on each document; spacing them 10, 20, 30 … leaves room to insert items later without renumbering everything.

2. Declare the column in the folder properties. Edit the folder's .docly file (in-place edits are safe — they preserve the schema binding). Set SpecifyCustomColumns to true and add a CustomColumns entry:

{
  "SpecifyCustomColumns": true,
  "CustomColumns": [
    {
      "Title": "Order",
      "Formula": "parseInt(Order)",
      "Sorting": "Sortable",
      "ROWID": "73d998f7-8d20-1538-bd62-a542bd9e0292"
    }
  ],
  "CustomColumns_type": "CustomColumns"
}

The ROWID can be any unique string — a GUID, or a readable slug like col-order.

3. Use parseInt() for numbers. parseInt(Order) sorts 1, 2, 3 … 10; a bare Order sorts the same values as text, giving 1, 10, 11, 2. Always wrap a numeric sort field.

4. Add more columns if useful. CustomColumns is an array, so you can show a non-sortable category beside a sortable order column:

"CustomColumns": [
  { "Title": "Kategori",  "Formula": "Kategori",        "Sorting": "No",       "ROWID": "col-kategori" },
  { "Title": "Sortering", "Formula": "parseInt(Order)", "Sorting": "Sortable", "ROWID": "col-order" }
]

5. Optional: set HideFilenameColumn to true to drop the default filename column when your custom columns already describe each row.

Live examples in production sort their contents exactly this way: /referanser, /tjenester, /faq and /råd-og-tips. See also Editing Docly documents programmatically for the rules on editing .docly files safely.