From ff4313309b0e56214ef4875e2c0aca2ab0306ab0 Mon Sep 17 00:00:00 2001 From: saberzero1 Date: Sat, 14 Feb 2026 02:13:01 +0100 Subject: [PATCH] docs: add plugin README --- README.md | 179 ++++++++++-------------------------------------------- 1 file changed, 33 insertions(+), 146 deletions(-) diff --git a/README.md b/README.md index 34d004a..8e595aa 100644 --- a/README.md +++ b/README.md @@ -1,165 +1,52 @@ -# Quartz Community Plugin Template +# @quartz-community/comments -Production-ready template for building, testing, and publishing Quartz community plugins. It mirrors -Quartz's native plugin patterns and uses a factory-function API similar to Astro integrations: -plugins are created by functions that return objects with `name` and lifecycle hooks. +Adds a comment section to pages using Giscus (GitHub Discussions-based). -## Highlights - -- ✅ Quartz-compatible transformer/filter/emitter examples -- ✅ TypeScript-first with exported types for consumers -- ✅ `tsup` bundling + declaration output -- ✅ Vitest testing setup with example tests -- ✅ Linting/formatting with ESLint + Prettier -- ✅ CI workflow for checks and npm publishing -- ✅ Demonstrates CSS/JS resource injection and remark/rehype usage - -## Getting started +## Installation ```bash -npm install -npm run build +npx quartz plugin add github:quartz-community/comments ``` -## Usage in Quartz - -Install your plugin into a Quartz site and register it in `quartz.config.ts`: +## Usage ```ts -import { - ExampleTransformer, - ExampleFilter, - ExampleEmitter, -} from "@quartz-community/plugin-template"; +// quartz.layout.ts +import * as Plugin from "./.quartz/plugins"; -export default { - configuration: { - pageTitle: "My Garden", +// Add to your layout +Plugin.Comments({ + provider: "giscus", + options: { + repo: "your-repo", + repoId: "your-repo-id", + category: "your-category", + categoryId: "your-category-id", }, - plugins: { - transformers: [ExampleTransformer({ highlightToken: "==" })], - filters: [ExampleFilter({ allowDrafts: false })], - emitters: [ExampleEmitter({ manifestSlug: "plugin-manifest" })], - }, -}; -``` - -## Plugin factory pattern (Astro-style) - -Quartz plugins are factory functions that return an object with a `name` and hook implementations. -This mirrors Astro's integration pattern (a function returning an object of hooks), which makes -composition and configuration explicit and predictable. - -```ts -import type { QuartzTransformerPlugin } from "@jackyzha0/quartz/plugins/types"; - -export const MyTransformer: QuartzTransformerPlugin<{ enabled: boolean }> = (opts) => { - return { - name: "MyTransformer", - markdownPlugins() { - return []; - }, - }; -}; -``` - -## Examples included - -### Transformer - -`ExampleTransformer` shows how to: - -- apply a custom remark plugin -- run a rehype plugin -- inject CSS/JS resources -- perform a text transform hook - -```ts -import { ExampleTransformer } from "@quartz-community/plugin-template"; - -ExampleTransformer({ - highlightToken: "==", - headingClass: "example-plugin-heading", - enableGfm: true, - addHeadingSlugs: true, }); ``` -The transformer uses a custom remark plugin to convert `==highlight==` into bold text and a rehype -plugin to attach a class to all headings. It also injects a small inline CSS/JS snippet. +## Configuration -### Filter +| Option | Type | Default | Description | +| -------------------------- | ------------------- | ----------- | ----------------------------------------------- | +| `provider` | `"giscus"` | - | The comment provider to use. | +| `options.repo` | `string` | - | The GitHub repository to use for comments. | +| `options.repoId` | `string` | - | The ID of the GitHub repository. | +| `options.category` | `string` | - | The GitHub Discussions category to use. | +| `options.categoryId` | `string` | - | The ID of the GitHub Discussions category. | +| `options.themeUrl` | `string` | `undefined` | Custom theme URL for Giscus. | +| `options.lightTheme` | `string` | `"light"` | The light theme for Giscus. | +| `options.darkTheme` | `string` | `"dark"` | The dark theme for Giscus. | +| `options.mapping` | `string` | `"url"` | The mapping between pages and discussions. | +| `options.strict` | `boolean` | `true` | Whether to use strict matching for discussions. | +| `options.reactionsEnabled` | `boolean` | `true` | Whether to enable reactions for comments. | +| `options.inputPosition` | `"top" \| "bottom"` | `"bottom"` | The position of the comment input box. | +| `options.lang` | `string` | `"en"` | The language for Giscus. | -`ExampleFilter` demonstrates frontmatter-driven filtering: +## Documentation -```ts -ExampleFilter({ - allowDrafts: false, - excludeTags: ["private", "wip"], - excludePathPrefixes: ["_drafts/", "_private/"], -}); -``` - -### Emitter - -`ExampleEmitter` emits a JSON manifest of all pages: - -```ts -ExampleEmitter({ - manifestSlug: "plugin-manifest", - includeFrontmatter: true, - metadata: { project: "My Garden" }, - transformManifest: (json) => json.replace("My Garden", "Quartz"), -}); -``` - -## API reference - -### `ExampleTransformer(options)` - -| Option | Type | Default | Description | -| ----------------- | --------- | -------------------------- | ----------------------------- | -| `highlightToken` | `string` | `"=="` | Token used to highlight text. | -| `headingClass` | `string` | `"example-plugin-heading"` | Class added to headings. | -| `enableGfm` | `boolean` | `true` | Enables `remark-gfm`. | -| `addHeadingSlugs` | `boolean` | `true` | Enables `rehype-slug`. | - -### `ExampleFilter(options)` - -| Option | Type | Default | Description | -| --------------------- | ---------- | --------------------------- | ------------------------- | -| `allowDrafts` | `boolean` | `false` | Publish draft pages. | -| `excludeTags` | `string[]` | `["private"]` | Tags to exclude. | -| `excludePathPrefixes` | `string[]` | `["_drafts/", "_private/"]` | Path prefixes to exclude. | - -### `ExampleEmitter(options)` - -| Option | Type | Default | Description | -| --------------------- | -------------------------- | ----------------------------------------- | ----------------------------------------- | -| `manifestSlug` | `string` | `"plugin-manifest"` | Output filename (without extension). | -| `includeFrontmatter` | `boolean` | `true` | Include frontmatter in output. | -| `metadata` | `Record` | `{ generator: "Quartz Plugin Template" }` | Extra metadata in manifest. | -| `transformManifest` | `(json: string) => string` | `undefined` | Custom transformer for emitted JSON. | -| `manifestScriptClass` | `string` | `undefined` | Optional CSS class if rendered into HTML. | - -## Testing - -```bash -npm test -``` - -## Build and lint - -```bash -npm run build -npm run lint -npm run format -``` - -## Publishing - -Tags matching `v*` trigger the GitHub Actions publish workflow. Ensure `NPM_TOKEN` is set in the -repository secrets. +See the [Quartz documentation](https://quartz.jzhao.xyz/) for more information. ## License