Skip to content

Migrating manual.md

Jump to bottom
SebastianMC edited this page Oct 23, 2023 · 2 revisions

This a copy of manual.md file from main github obsidian-custom sort repository. To be migrated here to wiki, updated and exposed instead to the original file. When completed, update the main github repo with a link to this file

Document is partial, creation in progress Please refer to README.md and advanced-README.md for more usage examples Check also syntax-reference.md

Some sections added ad-hoc, to be integrated later

Hints, tips & tricks

Adding visual separators in File Explorer

Do you want to have a nice-looking horizontal separators in File Explorer like this?

separators

If so, head on to Instruction and more context by @replete

This feature is not dependent on the Custom Sorting plugin. At the same time I'm mentioning it here because it is a side effect of a discussion with @replete. We were considering a direct support of the Separators in the plugin. Eventually this boiled down to a very concise and smart CSS-snippet based solution, independent of the plugin. Go, see, copy to the CSS-snippets in Obsidian and enjoy the more grouped look

Advanced features

Priorities of sorting groups

At run-time, when the custom sorting is triggered (explicitly or automatically) each folder item (a file or a sub-folder) is evaluated against the sorting groups. The evaluation (matching) is done in the order in which the sorting groups are defined in sorting-spec: | for the folder.

That means, for example, that the sorting group /:files ... will match all files - in turn, none of files has a chance to match further rule

Consider the below example:

---
sorting-spec: |
  target-folder: Some folder
       // The below sorting group captures (matches) all files
  /:files ...
       // The below sorting group should (theoretically) capture files with names starting with 'Archive' word
       //   yet none of files will have a chance to reach the rule, because the previous sorting group will match all files
       //   Hence, the below sorting group is void
  /:files Archive...
---

The resulting order of notes would be:

Order of notes w/o priorites

However, a group can be assigned a higher priority in the sorting spec. In result, folder items will be matched against them before any other rules. To impose a priority on a group use the prefix /! or /!! or /!!!

The modified example would be:

---
sorting-spec: |
  target-folder: Some folder
       // The below sorting group captures (matches) all files
  /:files ...
       // The below sorting group captures files with names starting with 'Archive' word
       //   and thanks to the priority indicator prefix '/!' folder items are matched against it
       //   before matching the previous sorting group
  /! /:files Archive...
---

and it would result in the expected order of items:

Order of notes with group priorites

For clarity: the three available prefixes /! and /!! and /!!! allow for futher finetuning of sorting groups matching order, the /!!! representing the highest priority value

A SIDE NOTE

In the above simplistic example, correct grouping of items can also be achieved in a different way: instead of using priorities, the first sorting group could be expressed differently as /:files (no following ... wildcard):

---
sorting-spec: |
  target-folder: Some folder
  /:files
  /:files Archive...
---

The sorting group expressed as /:files alone acts as a sorting group 'catch-all-files, which don't match any other sorting rule for the folder'

Simple wildcards

Currently, the below simple wildcard syntax is supported for sorting group:

A single digit (exactly one)

An expression like \d or \[0-9] matches a single digit (exactly one)

Example 1:

A group specification of /:files Section \d\d
matches notes with names Section 23 or Section 01, yet not a note like Section 5

An opposite example:

A group specification of /:files Section \d
matches the note with name Section 5 and doesn't match notes Section 23 or Section 01

However, be careful if used in connection with a wildcard ... - the behavior could be surprising:

A group specification of /:files Section \d...
matches all notes like Section 5, Section 23 or Section 015

Example 2:

As described above, the \d is equivalent to \[0-9] and can be used interchangeably
A group specification of /folders Notes of \[0-9]\[0-9]\[0-9]\[0-9]
matches the notes with titles like Notes of 2022 or Notes of 1999

Combining sorting groups

A prefix of /+ used in sorting group specification tells the sorting engine to combine the group with adjanced groups also prefixed with /+

Example:

The below sorting spec:

---
sorting-spec: |
  Notes \d\d\d\d
   > advanced modified
  Notes \d\d\d\d-\d\d
   > advanced modified
---

defines two sorting groups:

  • first go the notes or folders with title like Notes 2022 or Notes 1999
  • then go notes or folders like Notes 2022-12 or Notes 1999-11

Both groups sorted by recent modification date, the newest go first
Implicitly, all other files or folders go below these two groups

Using the /+ prefix you can combine the two groups into a logical one:

---
sorting-spec: |
  /+ Notes \d\d\d\d
  /+ Notes \d\d\d\d-\d\d
   > advanced modified
---

the result is that:

  • notes or folders with title like Notes 2022 or Notes 1999
  • AND
  • notes or folders like Notes 2022-12 or Notes 1999-11

will be pushed to the top in File Explorer, sorted by most recent modification date

NOTE: the sorting order is specified only once after the last of combined groups and it applies to the whole superset of items of all combined groups

An edge case: two adjacent combined sorting groups

If you want to define two combined groups one after another you should add a separator line with some artificial value not matching any of your folders or files. The text ---+--- was used in the below example:

---
sorting-spec: |
  /+ Zeta
  /+ % Gamma
  /+ /:files Beta
  /+ Alpha
    < a-z
  ---+--- 
  /+ Notes \d\d\d\d
  /+ Notes \d\d\d\d-\d\d
    > advanced modified
---

The artificial separator ---+--- defines a sorting group, which will not match any folders or files and is used here to logically separate the series of combined groups into to logical sets

Bookmarks plugin integration

Integration with the Bookmarks core plugin allows for ordering of items via drag & drop in Bookmarks view and reflecting the same order in File Explorer automatically

TODO: the simple scenario presented on movie

A separate group of bookmarks is designated by default, to separate from ...

If at least one item in folder is bookmarked and the auto-enabled, the order of the items becomes managed by the custom sort plugin

Auto-integration works without any need for sorting configuration files. Under the hood it is equivalent to applying the following global sorting specification:

---
sorting-spec: |
  target-folder: /*
  bookmarked:
    < by-bookmarks-order
  sorting: standard
---

Auto-integration doesn't apply to folders, for which explicit sorting specification is defined in YAML. In that case, if you want to employ the grouping and/or ordering by bookmarks order, you need to use explicit syntax:

---
sorting-spec: |
  target-folder: My folder
  bookmarked:
    < by-bookmarks-order
---

TODO: more instructions plus movie of advanced integration, where bookmarks reflect the folders structure

Also hints for updating

A folder is excluded from auto-integration if:

  • has custom sorting spec
    • you can (if needed) enable the auto-integration for part of the items
  • has explicitly applied 'sorting: standard'

Matching starred items

The Obsidian core plugin Starred allows the user to 'star' files
The keyword starred: allows matching such items. A folder is considered starred if at least one immediate child file is starred

Example

Consider the below sorting spec:

---
sorting-spec: |
  //       Example sorting configuration showing
    //     how to push the starred items to the top
    //
    // the line below applies the sorting specification
    //  to all folders in the vault
  target-folder: /*
    // the sorting order specification for the target folder(s)
  > advanced created 
    // the first group of items captures the files and folders which
    // are 'starred' in Obsidian core 'Starred' plugin.
    // Items in this group inherit the sorting order of target folder
  starred:
    // No further groups specified, which means all other items follow the
    // starred items, also in the order specified
---

The above sorting specification pushes the starred items to the top To achieve the opposite effect and push the starred items to the bottom, use the below sorting spec:

---
sorting-spec: |
  //       Example sorting configuration showing
    //     how to push the starred items to the bottom
    //
    // the line below applies the sorting specification
    //  to all folders in the vault
  target-folder: /*
    // the sorting order specification for the target folder(s)
  > a-z
    // the first group of items captures all of the files and folders which don't match any other sorting rule
    // Items in this group inherit the sorting order of target folder
  /folders:files
    // the second group of items captures the files and folders which
    // are 'starred' in Obsidian core 'Starred' plugin.
    // Items in this group also inherit the sorting order of target folder
  starred:
---

ADDITIONAL INFO

Because of UX concerns and additional performance considerations, the order of items in File Explorer
is not updated automatically after starring or un-starring an item. Please click-click the ribbon icon or use the sort-on command to refresh and re-apply the sorting rules

For a broader view, the same effect (as in previous example) can be achieved using the priorities of sorting rules:

---
sorting-spec: |
  //       Example sorting configuration showing
    //     how to push the starred items to the bottom
    //
    // the line below applies the sorting specification
    //  to all folders in the vault
  target-folder: /*
    // the sorting order specification for the target folder(s)
  > a-z
    // the first group of items captures all of the files and folders
    // Items in this group inherit the sorting order of target folder
  ...
    // the second group of items captures the files and folders which
    // are 'starred' in Obsidian core 'Starred' plugin.
    // Items in this group also inherit the sorting order of target folder
    // The priority '/!' indicator tells to evaluate this sorting rule before other rules
    // If it were not used, the prevoius rule '...' would eat all of the folders and items
    // and the starred items wouldn't be pushed to the bottom
  /! starred:
---

Options for target-folder: matching

The target-folder: has the following variants, listed in the order of precedence:

  1. match by the exact folder path (the default)
  2. match by the exact folder name
  3. match by regexp (for experts, be careful!)
  4. match by wildcard suffix (aka match folders subtree)

If a folder in the vault matches more than one target-folder: definitions, the above list shows the precedence, e.g. 1. has precedence over 2., 3. and 4. for example. In other words, match by exact folder path always wins, then goes the match by folder exact name, and so on.

If a folder in the vault matches more than one target-folder: definitions of the same type, see the detailed description below for the behavior

By folder path (the default)

If no additional modifiers follow the target-folder:, the remaining part of the line is treated as an exact folder path (leading and trailing spaces are ignored, infix spaces are treated literally as part of the folder path)

Within the same vault duplicate definitions of same path in target-folder: are detected and error is raised in that case, indicating the duplicated path

Examples of target-folder: with match by the exact folder path:

  • target-folder: My Folder
    • this refers to the folder in the root of the vault and only to it
  • target-folder: Archive/My Folder
    • matches the My Folder sub-folder in the Archive folder (a sub-folder of the root)
  • target-folder: .
    • this refers to path of the folder where the sorting specification resides (the specification containing the line, keep in mind that the sorting specification can reside in multiple locations in multiple notes)
  • target-folder: ./Some Subfolder
    • this refers to path of a sub-folder of the folder where the sorting specification resides (the specification containing the line, keep in mind that the sorting specification can reside in multiple locations in multiple notes)

By folder name

The modifier name: tells the target-folder: to match the folder name and not the full folder path

This is an exact match of the full folder name, no partial matching

Within the same vault duplicate definitions of same name in target-folder: name: are detected and error is raised in that case, indicating the duplicated folder name in sorting specification

Examples of target-folder: with match by the exact folder name:

  • target-folder: name: My Folder
    • matches all the folders with the name My Folder regardless of their location within the vault

By regexp (expert feature)

WARNING!!! This is an EXPERT FEATURE.

Involving and constructing the regexp-s requires at least basic knowledge about the potential pitfalls.
If you introduce a heavy regexp-backtracking it can kill performance of Obsidian and even make it unresponsive
If you don't know what the regexp-backtracking is, be careful when using regexp for target-folder:

The modifier regexp: tells the target-folder: to involve the specified regular expressions in matching

Additional dependent modifiers are supported for regexp::

  • for-name:
    • tells the matching to be done against the folder name, not the full path
  • debug:
    • tells the regexp to report its match in the developer console, so that you can easily investigate why the regexp matches (or why it doesn't match) as expected
  • /!: /!!: /!!!:
    • sets the priority of the regexp

By default, the regexp is matched against the full path of the folder, unless the for-name: modifiers tells otherwise.

By default, the regexp-es have no priority and are evaluated in the order of their definition.
If you store sorting-spec: configurations in notes spread all over the vault, consider the order of target-folder: regexp: to be undefined and - if needed - use explicit priority modifiers (/!: /!!: /!!!:) to impose the desired order of matching.

  • a regexp with modifier /!!!: if evaluated before all other regexps, regardless of where they are configured
    • if two or more regexps are stamped with /!!!:, they are matched in the order in which they were defined.
      Within a single YAML section of a note the order is obvious.
      For sorting specifications spread over many notes in the vault consider the order to be undefined.
  • a regexp with modifier /!!: if evaluated after any /!!!: and before all other regexps
    • the same logic as described above applies when multiple regexps have the /!!: stamp
  • a regexp with modifier /!: indicates the lowest of explicitly defined priorities.
    Such a regexp is matched after all priority-stamped regexps, before the regexps not having any explicit priority stamp

The escape character is \ - the standard one in regexp world.

Examples of target-folder: with match by regexp:

  • target-folder: regexp: reading
    • matches any folder which contains the word reading in its path or name
  • target-folder: regexp: \d?\d-\d?\d-\d\d\d\d$
    • matches any folder which ends with date-alike numerical expression, e.g.:
      • 1-1-2023
      • Archive/Monthly/12/05-12-2022
      • Inbox/Not digested notes from 20-7-2019
  • target-folder: regexp: for-name: I am everywhere
    • matches all folders which contain the phrase I am everywhere in their name, e.g.:
      • Reports/Not processed/What the I am everywhere report from Paul means?
      • Chapters/I am everywhere
  • target-folder: regexp: for-name: ^I am (everyw)?here$
    • matches all folders with name exactly I am everywhere or I am here
  • target-folder: regexp: for-name: debug: ^...$
    • matches all folders with name comprising exactly 3 character
    • when a folder is matched, a diagnostic line is written to the console - debug: modifiers enables the logging
  • target-folder: regexp: debug: ^.{13,15}$
    • matches all folders with path length between 13 and 15 characters
    • diagnostic line is written to the console due to debug:
  • target-folder: regexp: for-name: /!: ^[aA]
    • matches all folders with name starting with a or A
    • the priority /!: modifier causes the matching to be done before all other regexps which don't have any priority
  • target-folder: regexp: /!!!: debug: for-name: abc|def|ghi
    • matches all folders with name containing the sequence abc or def or ghi
    • the modifier /!!!: imposes the highest priority of regexp matching
    • debug: tells to report each matching folder in the console
  • target-folder: regexp: ^[^/]+/[^/]+$
    • matches all folders which are at the 2nd level of vault tree, e.g.:
      • Inbox/Priority input
      • Archive/2021
  • target-folder: regexp: ^[^\/]+(\/[^\/]+){2}$
    • matches all folders which are at the 3rd level of vault tree, e.g.:
    • Archive/2019/05
    • Aaaa/Bbbb/Test test

By wildcard

In the default usage of target-folder: with the exact full folder path, if the path contains the /... or /* suffix its meaning is extended to:

  • match the folder and all its immediate (child) subfolders - /... suffix
  • match the folder and all its subfolders at any level (all descendants, the entire subtree) - /* suffix

For example:

  • target-folder: /*
    • matches all folders in the vault (the root folder and all its descendants)
  • target-folder: /...
    • matches the root folder and its immediate children (aka immediate subfolders of the root)

If the sorting specification contains duplicate wildcard-ed path in target-folder: an error is raised, indicating the duplicate path

If a folder is matched by two (or more) wildcarded paths, the one with more path segments (the deeper one) wins. For example:

  • a folder Book/Chapters/12/a is matched by:
    • (a) target-folder: Book/*, and
    • (b) target-folder: Book/Chapters/*
    • In this case the (b) wins, because it contains a deeper path

If the depth of matches specification is the same, the /... takes precedence over /*

  • a folder Book/Appendix/III is matched by:
    • (a) target-folder: Book/Appendix/..., and
    • (b) target-folder: Book/Appendix/*
    • In this case the (a) wins

Excluding folders from custom sorting

Having the ability to wildard- and regexp-based match of target-folder: in some cases you might want to exclude folder(s) from custom sorting.

This can be done by combination of the target-folder: (in any of its variants) and specification of the sort order as sorting: standard

An example piece of YAML frontmatter could look like:

---
sorting-spec: |

  // ... some sorting specification above
 
  target-folder: Reviews/Attachments
  target-folder: TODOs
  sorting: standard
 
  // ... some sorting specification below 
  
---

Table of contents:

Clone this wiki locally