From 965425d54d801c29c65dac7f21f92485be8405f5 Mon Sep 17 00:00:00 2001 From: Jacky Zhao Date: Tue, 9 Jul 2024 17:55:19 -0700 Subject: [PATCH] docs + chore: cleanup custom sort ordering for folder + tag listings, add docs --- docs/features/folder and tag listings.md | 2 +- docs/plugins/FolderPage.md | 6 ++++-- docs/plugins/TagPage.md | 6 ++++-- quartz/components/PageList.tsx | 8 ++++---- quartz/components/pages/FolderContent.tsx | 5 ++--- quartz/components/pages/TagContent.tsx | 24 +++++++++++++++++------ quartz/plugins/emitters/folderPage.tsx | 8 +++++--- quartz/plugins/emitters/tagPage.tsx | 8 +++++--- 8 files changed, 43 insertions(+), 24 deletions(-) diff --git a/docs/features/folder and tag listings.md b/docs/features/folder and tag listings.md index d330f1479..3190709d3 100644 --- a/docs/features/folder and tag listings.md +++ b/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. diff --git a/docs/plugins/FolderPage.md b/docs/plugins/FolderPage.md index ead8e75ff..45cfa1574 100644 --- a/docs/plugins/FolderPage.md +++ b/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 diff --git a/docs/plugins/TagPage.md b/docs/plugins/TagPage.md index 9c704b380..9556363fe 100644 --- a/docs/plugins/TagPage.md +++ b/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 diff --git a/quartz/components/PageList.tsx b/quartz/components/PageList.tsx index 2512b6293..8dc19b74c 100644 --- a/quartz/components/PageList.tsx +++ b/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( - cfg: GlobalConfiguration, -): (f1: QuartzPluginData, f2: QuartzPluginData) => number { +export type SortFn = (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) => { diff --git a/quartz/components/pages/FolderContent.tsx b/quartz/components/pages/FolderContent.tsx index e01496c75..dc216cde7 100644 --- a/quartz/components/pages/FolderContent.tsx +++ b/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 = { diff --git a/quartz/components/pages/TagContent.tsx b/quartz/components/pages/TagContent.tsx index 7598b13a4..e41ab4644 100644 --- a/quartz/components/pages/TagContent.tsx +++ b/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 }) => { - const numPages = 10 +interface TagContentOptions { + sort?: SortFn + numPages: number +} + +const defaultOptions: TagContentOptions = { + numPages: 10, +} + +export default ((opts?: Partial) => { + 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) =>

{i18n(cfg.locale).pages.tagContent.itemsUnderTag({ count: pages.length })} - {pages.length > numPages && ( + {pages.length > options.numPages && ( <> {" "} - {i18n(cfg.locale).pages.tagContent.showingFirst({ count: numPages })} + {i18n(cfg.locale).pages.tagContent.showingFirst({ + count: options.numPages, + })} )}

- +
) diff --git a/quartz/plugins/emitters/folderPage.tsx b/quartz/plugins/emitters/folderPage.tsx index bd17e57e2..cd154f415 100644 --- a/quartz/plugins/emitters/folderPage.tsx +++ b/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< - Partial & { sort?: (f1: QuartzPluginData, f2: QuartzPluginData) => number } -> = (userOpts) => { +interface FolderPageOptions extends FullPageLayout { + sort?: (f1: QuartzPluginData, f2: QuartzPluginData) => number +} + +export const FolderPage: QuartzEmitterPlugin> = (userOpts) => { const opts: FullPageLayout = { ...sharedPageComponents, ...defaultListPageLayout, diff --git a/quartz/plugins/emitters/tagPage.tsx b/quartz/plugins/emitters/tagPage.tsx index 3994140df..9b727ebd1 100644 --- a/quartz/plugins/emitters/tagPage.tsx +++ b/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< - Partial & { sort?: (f1: QuartzPluginData, f2: QuartzPluginData) => number } -> = (userOpts) => { +interface TagPageOptions extends FullPageLayout { + sort?: (f1: QuartzPluginData, f2: QuartzPluginData) => number +} + +export const TagPage: QuartzEmitterPlugin> = (userOpts) => { const opts: FullPageLayout = { ...sharedPageComponents, ...defaultListPageLayout,