245 lines
8.3 KiB
Markdown
245 lines
8.3 KiB
Markdown
> Document is partial, creation in progress
|
|
> Please refer to [README.md](../README.md) for more usage examples
|
|
> Check also [syntax-reference.md](./syntax-reference.md)
|
|
|
|
---
|
|
Some sections added ad-hoc, to be integrated later
|
|
|
|
# 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:
|
|
```yaml
|
|
---
|
|
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:
|
|
|
|
|
|
|
|
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:
|
|
```yaml
|
|
---
|
|
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:
|
|
|
|
|
|
|
|
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):
|
|
> ```yaml
|
|
> ---
|
|
> 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:
|
|
|
|
### 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:
|
|
```yaml
|
|
---
|
|
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:
|
|
```yaml
|
|
---
|
|
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:
|
|
|
|
```yaml
|
|
---
|
|
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
|
|
|
|
## 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:
|
|
```yaml
|
|
---
|
|
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:
|
|
|
|
```yaml
|
|
---
|
|
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:
|
|
---
|
|
```
|
|
|
|
For a broader view, the same effect (as in previous example) can be achieved using the priorities
|
|
of sorting rules:
|
|
|
|
```yaml
|
|
---
|
|
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:
|
|
---
|
|
```
|