13 - Feature request: Sort by modification date, treating folder and files equally

- finetuned the 'modified' sorting method - not the folders are ordered alphabetically, as the standard Obsidiand sort by 'modified date' does
- finetuned the 'created' sorting method in the same way as 'modified'
- added some initial content to syntax-reference.md ;-)
- extended the 'advanced modified' sorting method to also support the edge-case secondary sorting methods for groups

docs/syntax-reference.md

@@ -1,3 +1,41 @@
-Yet to be filled with content ;-)
+> Document is partial, creation in progress
+> Please refer to [README.md](../../README.md) for usage examples
+> Check [manual.md](), maybe that file has already some content?
 
-Check [manual.md](), maybe that file has already some content?
+### Supported sorting methods
+
+#### At folder level only
+
+- `sorting: standard` - gives back the control on order of items in hands of standard Obsidian mechanisms (UI driven).
+ Typical (and intended) use: exclude a folder (or folders subtree) from a custom sorting resulting from wilcard-based target folder rule 
+
+#### At folder and group level
+
+- `< a-z` - alphabetical
+- `> a-z` - alphabetical reverse, aka alphabetical descending, 'z' goes before 'a'
+- `< modified` - by modified time, the long untouched item goes first (modified time of folder is assumed the beginning of the world, so folders go first and alphabetical)
+- `> modified` - by modified time reverse, the most recently modified item goes first (modified time of folder is assumed the beginning of the world, so folders land in the bottom and alphabetical)
+- `< created` - by created time, the oldest item goes first (modified time of folder is assumed the beginning of the world, so folders go first and alphabetical) 
+- `> created` - by created time reverse, the newest item goes first (modified time of folder is assumed the beginning of the world, so folders land in the bottom and alphabetical)
+- `< advanced modified` - by modified time, the long untouched item goes first. For folders, their modification date is derived from the most recently modified direct child file.
+ For extremely large vaults use with caution, as the sorting needs to scan all files inside a folder to determine the folder's modified date
+- `> advanced modified` - by modified time reverse, the most recently modified item goes first. For folders, their modification date is derived from the most recently modified direct child file.
+  For extremely large vaults use with caution, as the sorting needs to scan all files inside a folder to determine the folder's modified date
+
+#### At group level only (aka secondary sorting rule)
+
+> Only applicable in edge cases based on numerical symbols, when the regex-based match is equal for more than one item
+ and need to apply a secondary order on same matches.
+
+- `< a-z, created`
+- `> a-z, created`
+- `< a-z, created desc`
+- `> a-z, created desc`
+- `< a-z, modified`
+- `> a-z, modified`
+- `< a-z, modified desc`
+- `> a-z, modified desc`
+- `< a-z, advanced modified`
+- `> a-z, advanced modified`
+- `< a-z, advanced modified desc`
+- `> a-z, advanced modified desc`

src/custom-sort/custom-sort.ts

@@ -24,12 +24,12 @@ type SorterFn = (a: FolderItemForSorting, b: FolderItemForSorting) => number
 let Sorters: { [key in CustomSortOrder]: SorterFn } = {
 	[CustomSortOrder.alphabetical]: (a: FolderItemForSorting, b: FolderItemForSorting) => Collator(a.sortString, b.sortString),
 	[CustomSortOrder.alphabeticalReverse]: (a: FolderItemForSorting, b: FolderItemForSorting) => Collator(b.sortString, a.sortString),
-	[CustomSortOrder.byModifiedTime]: (a: FolderItemForSorting, b: FolderItemForSorting) => a.mtime - b.mtime,
+	[CustomSortOrder.byModifiedTime]: (a: FolderItemForSorting, b: FolderItemForSorting) => (a.isFolder && b.isFolder) ? Collator(a.sortString, b.sortString) : (a.mtime - b.mtime),
 	[CustomSortOrder.byModifiedTimeAdvanced]: (a: FolderItemForSorting, b: FolderItemForSorting) => a.mtime - b.mtime,
-	[CustomSortOrder.byModifiedTimeReverse]: (a: FolderItemForSorting, b: FolderItemForSorting) => b.mtime - a.mtime,
+	[CustomSortOrder.byModifiedTimeReverse]: (a: FolderItemForSorting, b: FolderItemForSorting) => (a.isFolder && b.isFolder) ? Collator(a.sortString, b.sortString) : (b.mtime - a.mtime),
 	[CustomSortOrder.byModifiedTimeReverseAdvanced]: (a: FolderItemForSorting, b: FolderItemForSorting) => b.mtime - a.mtime,
-	[CustomSortOrder.byCreatedTime]: (a: FolderItemForSorting, b: FolderItemForSorting) => a.ctime - b.ctime,
+	[CustomSortOrder.byCreatedTime]: (a: FolderItemForSorting, b: FolderItemForSorting) => (a.isFolder && b.isFolder) ? Collator(a.sortString, b.sortString) : (a.ctime - b.ctime),
-	[CustomSortOrder.byCreatedTimeReverse]: (a: FolderItemForSorting, b: FolderItemForSorting) => b.ctime - a.ctime,
+	[CustomSortOrder.byCreatedTimeReverse]: (a: FolderItemForSorting, b: FolderItemForSorting) => (a.isFolder && b.isFolder) ? Collator(a.sortString, b.sortString) : (b.ctime - a.ctime),
 
 	// This is a fallback entry which should not be used - the plugin code should refrain from custom sorting at all
 	[CustomSortOrder.standardObsidian]: (a: FolderItemForSorting, b: FolderItemForSorting) => Collator(a.sortString, b.sortString),
@@ -178,8 +178,11 @@ export const determineSortingGroup = function (entry: TFile | TFolder, spec: Cus
 	}
 }
 
-export const sortOrderNeedsFoldersMDate = (order: CustomSortOrder | undefined): boolean => {
+export const sortOrderNeedsFoldersMDate = (order: CustomSortOrder | undefined, secondary?: CustomSortOrder): boolean => {
-	return order === CustomSortOrder.byModifiedTimeAdvanced || order === CustomSortOrder.byModifiedTimeReverseAdvanced
+	return order === CustomSortOrder.byModifiedTimeAdvanced
+		|| order === CustomSortOrder.byModifiedTimeReverseAdvanced
+		|| secondary === CustomSortOrder.byModifiedTimeAdvanced
+		|| secondary === CustomSortOrder.byModifiedTimeReverseAdvanced
 }
 
 // Syntax sugar for readability

src/custom-sort/sorting-spec-processor.ts

@@ -108,6 +108,16 @@ const OrderLiterals: { [key: string]: CustomSortOrderAscDescPair } = {
 		asc: CustomSortOrder.alphabetical,
 		desc: CustomSortOrder.alphabeticalReverse,
 		secondary: CustomSortOrder.byModifiedTimeReverse
+	},
+	'a-z, advanced modified': {
+		asc: CustomSortOrder.alphabetical,
+		desc: CustomSortOrder.alphabeticalReverse,
+		secondary: CustomSortOrder.byModifiedTimeAdvanced
+	},
+	'a-z, advanced modified desc': {
+		asc: CustomSortOrder.alphabetical,
+		desc: CustomSortOrder.alphabeticalReverse,
+		secondary: CustomSortOrder.byModifiedTimeReverseAdvanced
 	}
 }