From 965425d54d801c29c65dac7f21f92485be8405f5 Mon Sep 17 00:00:00 2001
From: Jacky Zhao <j.zhao2k19@gmail.com>
Date: Wed, 10 Jul 2024 00:55:19 +0000
Subject: [PATCH] docs + chore: cleanup custom sort ordering for folder + tag listings, add docs
---
docs/plugins/TagPage.md | 6 ++-
quartz/components/PageList.tsx | 8 ++--
quartz/plugins/emitters/tagPage.tsx | 8 ++-
docs/features/folder and tag listings.md | 2
quartz/plugins/emitters/folderPage.tsx | 8 ++-
quartz/components/pages/TagContent.tsx | 24 +++++++++---
docs/plugins/FolderPage.md | 6 ++-
quartz/components/pages/FolderContent.tsx | 5 +-
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 d330f14..3190709 100644
--- a/docs/features/folder and tag listings.md
+++ b/docs/features/folder and tag listings.md
@@ -30,4 +30,4 @@
## 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 ead8e75..45cfa15 100644
--- a/docs/plugins/FolderPage.md
+++ b/docs/plugins/FolderPage.md
@@ -11,10 +11,12 @@
> [!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 9c704b3..9556363 100644
--- a/docs/plugins/TagPage.md
+++ b/docs/plugins/TagPage.md
@@ -9,10 +9,12 @@
> [!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 2512b62..8dc19b7 100644
--- a/quartz/components/PageList.tsx
+++ b/quartz/components/PageList.tsx
@@ -4,9 +4,9 @@
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 @@
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 e01496c..dc216cd 100644
--- a/quartz/components/pages/FolderContent.tsx
+++ b/quartz/components/pages/FolderContent.tsx
@@ -2,19 +2,18 @@
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 7598b13..e41ab46 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<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 @@
<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>
)
diff --git a/quartz/plugins/emitters/folderPage.tsx b/quartz/plugins/emitters/folderPage.tsx
index bd17e57..cd154f4 100644
--- a/quartz/plugins/emitters/folderPage.tsx
+++ b/quartz/plugins/emitters/folderPage.tsx
@@ -21,9 +21,11 @@
import { i18n } from "../../i18n"
import DepGraph from "../../depgraph"
-export const FolderPage: QuartzEmitterPlugin<
- Partial<FullPageLayout> & { sort?: (f1: QuartzPluginData, f2: QuartzPluginData) => number }
-> = (userOpts) => {
+interface FolderPageOptions extends FullPageLayout {
+ sort?: (f1: QuartzPluginData, f2: QuartzPluginData) => number
+}
+
+export const FolderPage: QuartzEmitterPlugin<Partial<FolderPageOptions>> = (userOpts) => {
const opts: FullPageLayout = {
...sharedPageComponents,
...defaultListPageLayout,
diff --git a/quartz/plugins/emitters/tagPage.tsx b/quartz/plugins/emitters/tagPage.tsx
index 3994140..9b727eb 100644
--- a/quartz/plugins/emitters/tagPage.tsx
+++ b/quartz/plugins/emitters/tagPage.tsx
@@ -18,9 +18,11 @@
import { i18n } from "../../i18n"
import DepGraph from "../../depgraph"
-export const TagPage: QuartzEmitterPlugin<
- Partial<FullPageLayout> & { sort?: (f1: QuartzPluginData, f2: QuartzPluginData) => number }
-> = (userOpts) => {
+interface TagPageOptions extends FullPageLayout {
+ sort?: (f1: QuartzPluginData, f2: QuartzPluginData) => number
+}
+
+export const TagPage: QuartzEmitterPlugin<Partial<TagPageOptions>> = (userOpts) => {
const opts: FullPageLayout = {
...sharedPageComponents,
...defaultListPageLayout,
--
Gitblit v1.10.0