docs + chore: cleanup custom sort ordering for folder + tag listings, add docs

docs/features/folder and tag listings.md

@@ -30,4 +30,4 @@ As with folder listings, you can also provide a description and title for a tag
 
 ## Customization
 
-The folder listings are a functionality of the [[FolderPage]] plugin, the tag listings of the [[TagPage]] plugin. See the plugin pages for customization options.
+Quartz allows you to define a custom sort ordering for content on both page types. The folder listings are a functionality of the [[FolderPage]] plugin, the tag listings of the [[TagPage]] plugin. See the plugin pages for customization options.

docs/plugins/FolderPage.md

@@ -11,10 +11,12 @@ Example: [[advanced/|Advanced]]
 > [!note]
 > For information on how to add, remove or configure plugins, see the [[configuration#Plugins|Configuration]] page.
 
-This plugin has no configuration options.
-
 The pages are displayed using the `defaultListPageLayout` in `quartz.layouts.ts`. For the content, the `FolderContent` component is used. If you want to modify the layout, you must edit it directly (`quartz/components/pages/FolderContent.tsx`).
 
+This plugin accepts the following configuration options:
+
+- `sort`: A function of type `(f1: QuartzPluginData, f2: QuartzPluginData) => number{:ts}` used to sort entries. Defaults to sorting by date and tie-breaking on lexographical order.
+
 ## API
 
 - Category: Emitter

docs/plugins/TagPage.md

@@ -9,10 +9,12 @@ This plugin emits dedicated pages for each tag used in the content. See [[folder
 > [!note]
 > For information on how to add, remove or configure plugins, see the [[configuration#Plugins|Configuration]] page.
 
-This plugin has no configuration options.
-
 The pages are displayed using the `defaultListPageLayout` in `quartz.layouts.ts`. For the content, the `TagContent` component is used. If you want to modify the layout, you must edit it directly (`quartz/components/pages/TagContent.tsx`).
 
+This plugin accepts the following configuration options:
+
+- `sort`: A function of type `(f1: QuartzPluginData, f2: QuartzPluginData) => number{:ts}` used to sort entries. Defaults to sorting by date and tie-breaking on lexographical order.
+
 ## API
 
 - Category: Emitter

quartz/components/PageList.tsx

@@ -4,9 +4,9 @@ import { Date, getDate } from "./Date"
 import { QuartzComponent, QuartzComponentProps } from "./types"
 import { GlobalConfiguration } from "../cfg"
 
-export function byDateAndAlphabetical(
+export type SortFn = (f1: QuartzPluginData, f2: QuartzPluginData) => number
-  cfg: GlobalConfiguration,
+
-): (f1: QuartzPluginData, f2: QuartzPluginData) => number {
+export function byDateAndAlphabetical(cfg: GlobalConfiguration): SortFn {
   return (f1, f2) => {
     if (f1.dates && f2.dates) {
       // sort descending
@@ -27,7 +27,7 @@ export function byDateAndAlphabetical(
 
 type Props = {
   limit?: number
-  sort?: (f1: QuartzPluginData, f2: QuartzPluginData) => number
+  sort?: SortFn
 } & QuartzComponentProps
 
 export const PageList: QuartzComponent = ({ cfg, fileData, allFiles, limit, sort }: Props) => {

quartz/components/pages/FolderContent.tsx

@@ -2,19 +2,18 @@ import { QuartzComponent, QuartzComponentConstructor, QuartzComponentProps } fro
 import path from "path"
 
 import style from "../styles/listPage.scss"
-import { PageList } from "../PageList"
+import { PageList, SortFn } from "../PageList"
 import { stripSlashes, simplifySlug } from "../../util/path"
 import { Root } from "hast"
 import { htmlToJsx } from "../../util/jsx"
 import { i18n } from "../../i18n"
-import { QuartzPluginData } from "../../plugins/vfile"
 
 interface FolderContentOptions {
   /**
    * Whether to display number of folders
    */
   showFolderCount: boolean
-  sort?: (f1: QuartzPluginData, f2: QuartzPluginData) => number
+  sort?: SortFn
 }
 
 const defaultOptions: FolderContentOptions = {

quartz/components/pages/TagContent.tsx

@@ -1,14 +1,24 @@
 import { QuartzComponent, QuartzComponentConstructor, QuartzComponentProps } from "../types"
 import style from "../styles/listPage.scss"
-import { PageList } from "../PageList"
+import { PageList, SortFn } from "../PageList"
 import { FullSlug, getAllSegmentPrefixes, simplifySlug } from "../../util/path"
 import { QuartzPluginData } from "../../plugins/vfile"
 import { Root } from "hast"
 import { htmlToJsx } from "../../util/jsx"
 import { i18n } from "../../i18n"
 
-export default ((opts?: { sort?: (f1: QuartzPluginData, f2: QuartzPluginData) => number }) => {
+interface TagContentOptions {
-  const numPages = 10
+  sort?: SortFn
+  numPages: number
+}
+
+const defaultOptions: TagContentOptions = {
+  numPages: 10,
+}
+
+export default ((opts?: Partial<TagContentOptions>) => {
+  const options: TagContentOptions = { ...defaultOptions, ...opts }
+
   const TagContent: QuartzComponent = (props: QuartzComponentProps) => {
     const { tree, fileData, allFiles, cfg } = props
     const slug = fileData.slug
@@ -72,16 +82,18 @@ export default ((opts?: { sort?: (f1: QuartzPluginData, f2: QuartzPluginData) =>
                   <div class="page-listing">
                     <p>
                       {i18n(cfg.locale).pages.tagContent.itemsUnderTag({ count: pages.length })}
-                      {pages.length > numPages && (
+                      {pages.length > options.numPages && (
                         <>
                           {" "}
                           <span>
-                            {i18n(cfg.locale).pages.tagContent.showingFirst({ count: numPages })}
+                            {i18n(cfg.locale).pages.tagContent.showingFirst({
+                              count: options.numPages,
+                            })}
                           </span>
                         </>
                       )}
                     </p>
-                    <PageList limit={numPages} {...listProps} sort={opts?.sort} />
+                    <PageList limit={options.numPages} {...listProps} sort={opts?.sort} />
                   </div>
                 </div>
               )

quartz/plugins/emitters/folderPage.tsx

@@ -21,9 +21,11 @@ import { write } from "./helpers"
 import { i18n } from "../../i18n"
 import DepGraph from "../../depgraph"
 
-export const FolderPage: QuartzEmitterPlugin<
+interface FolderPageOptions extends FullPageLayout {
-  Partial<FullPageLayout> & { sort?: (f1: QuartzPluginData, f2: QuartzPluginData) => number }
+  sort?: (f1: QuartzPluginData, f2: QuartzPluginData) => number
-> = (userOpts) => {
+}
+
+export const FolderPage: QuartzEmitterPlugin<Partial<FolderPageOptions>> = (userOpts) => {
   const opts: FullPageLayout = {
     ...sharedPageComponents,
     ...defaultListPageLayout,

quartz/plugins/emitters/tagPage.tsx

@@ -18,9 +18,11 @@ import { write } from "./helpers"
 import { i18n } from "../../i18n"
 import DepGraph from "../../depgraph"
 
-export const TagPage: QuartzEmitterPlugin<
+interface TagPageOptions extends FullPageLayout {
-  Partial<FullPageLayout> & { sort?: (f1: QuartzPluginData, f2: QuartzPluginData) => number }
+  sort?: (f1: QuartzPluginData, f2: QuartzPluginData) => number
-> = (userOpts) => {
+}
+
+export const TagPage: QuartzEmitterPlugin<Partial<TagPageOptions>> = (userOpts) => {
   const opts: FullPageLayout = {
     ...sharedPageComponents,
     ...defaultListPageLayout,