@quartz-community/unlisted-pages 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Initial release.
+- `UnlistedPages` transformer: zero-config rehype plugin that copies `file.data.frontmatter.unlisted` to `file.data.unlisted` when it is a boolean. Enables the `file.data.unlisted` convention respected by `content-index`, `search`, `backlinks`, `recent-notes`, `folder-page`, and `tag-page` to work for any page, not only encrypted ones.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Quartz Community
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,81 @@
+# @quartz-community/unlisted-pages
+
+Zero-config transformer that bridges `frontmatter.unlisted` to `file.data.unlisted` so any page can opt out of discovery surfaces while remaining accessible by direct URL.
+
+## What it does
+
+Quartz v5 plugins that respect the `file.data.unlisted` convention — `content-index`, `search`, `backlinks`, `recent-notes`, `folder-page`, and `tag-page` — will hide a page from their output when `file.data.unlisted === true`. But nothing in the core pipeline copies `frontmatter.unlisted` onto `file.data.unlisted`, so a user writing:
+
+```yaml
+---
+title: My Draft
+unlisted: true
+---
+```
+
+gets no effect. This plugin fixes that. It is a trivially small rehype plugin that does one thing: if `frontmatter.unlisted` is a boolean, copy it to `file.data.unlisted`.
+
+## Installation
+
+```bash
+npx quartz plugin add github:quartz-community/unlisted-pages
+```
+
+## Usage
+
+Add an `unlisted` field to any page's frontmatter:
+
+```yaml
+---
+title: My Draft
+unlisted: true
+---
+```
+
+When registered, this plugin marks the page as unlisted. Every Quartz v5 plugin that respects the convention will then hide it:
+
+- **Absent from** `contentIndex.json`, `sitemap.xml`, the RSS feed, backlinks, recent notes, folder listings, tag listings, graph, explorer, and search.
+- **Still emitted** as HTML, so the page remains accessible by direct URL.
+
+## Configuration
+
+Zero options. Just enable it.
+
+```yaml title="quartz.config.yaml"
+- source: github:quartz-community/unlisted-pages
+  enabled: true
+```
+
+## Interaction with `@quartz-community/encrypted-pages`
+
+The `encrypted-pages` plugin also sets `file.data.unlisted` when `unlistWhenEncrypted: true` or when per-page frontmatter specifies `unlisted: true`. The two plugins compose cleanly:
+
+- If you install only `unlisted-pages`: any page with `unlisted: true` in frontmatter is hidden from listing surfaces. Encryption is independent.
+- If you install only `encrypted-pages`: `unlisted: true` only works on pages that are ALSO encrypted (have a password). Non-encrypted pages with `unlisted: true` are silently ignored.
+- If you install both: `unlisted: true` works for every page, encrypted or not. This is the recommended setup for sites that use encrypted pages.
+
+## How `unlisted` works across consumer plugins
+
+| Plugin          | Behavior when `file.data.unlisted === true`                                |
+| --------------- | -------------------------------------------------------------------------- |
+| `content-index` | Page absent from `contentIndex.json`, `sitemap.xml`, and the RSS feed.     |
+| `search`        | Page absent from search results (derived from `contentIndex.json`).        |
+| `graph`         | Page absent from graph nodes and edges (derived from `contentIndex.json`). |
+| `explorer`      | Page absent from the sidebar file tree (derived from `contentIndex.json`). |
+| `backlinks`     | Page never appears as a backlink source on other pages.                    |
+| `recent-notes`  | Page absent from the recent notes list.                                    |
+| `folder-page`   | Page absent from folder listings and folder discovery.                     |
+| `tag-page`      | Page absent from tag listings and tag discovery.                           |
+
+In every case, the page's HTML is still emitted and accessible by direct URL.
+
+## API
+
+- Category: Transformer
+- Function name: `UnlistedPages()`
+- Source: [`quartz-community/unlisted-pages`](https://github.com/quartz-community/unlisted-pages)
+- Install: `npx quartz plugin add github:quartz-community/unlisted-pages`
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { QuartzTransformerPlugin } from '@quartz-community/types';
+export { QuartzPluginData, QuartzTransformerPlugin, QuartzTransformerPluginInstance } from '@quartz-community/types';
+
+declare const UnlistedPages: QuartzTransformerPlugin<undefined>;
+
+export { UnlistedPages };

package/dist/index.js

@@ -0,0 +1,22 @@
+// src/transformer.ts
+var rehypeUnlisted = () => {
+  return () => (_tree, file) => {
+    const frontmatter = file.data?.frontmatter;
+    const unlisted = frontmatter?.unlisted;
+    if (typeof unlisted === "boolean") {
+      file.data.unlisted = unlisted;
+    }
+  };
+};
+var UnlistedPages = () => {
+  return {
+    name: "UnlistedPages",
+    htmlPlugins() {
+      return [rehypeUnlisted()];
+    }
+  };
+};
+
+export { UnlistedPages };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/transformer.ts"],"names":[],"mappings":";AAKA,IAAM,iBAAiB,MAA4B;AACjD,EAAA,OAAO,MAAM,CAAC,KAAA,EAAiB,IAAA,KAAgB;AAC7C,IAAA,MAAM,WAAA,GAAc,KAAK,IAAA,EAAM,WAAA;AAC/B,IAAA,MAAM,WAAW,WAAA,EAAa,QAAA;AAC9B,IAAA,IAAI,OAAO,aAAa,SAAA,EAAW;AACjC,MAAC,IAAA,CAAK,KAAiC,QAAA,GAAW,QAAA;AAAA,IACpD;AAAA,EACF,CAAA;AACF,CAAA;AAEO,IAAM,gBAAoD,MAAM;AACrE,EAAA,OAAO;AAAA,IACL,IAAA,EAAM,eAAA;AAAA,IACN,WAAA,GAA6B;AAC3B,MAAA,OAAO,CAAC,gBAAgB,CAAA;AAAA,IAC1B;AAAA,GACF;AACF","file":"index.js","sourcesContent":["import type { PluggableList, Plugin } from \"unified\";\nimport type { Root as HastRoot } from \"hast\";\nimport type { VFile } from \"vfile\";\nimport type { QuartzTransformerPlugin } from \"@quartz-community/types\";\n\nconst rehypeUnlisted = (): Plugin<[], HastRoot> => {\n  return () => (_tree: HastRoot, file: VFile) => {\n    const frontmatter = file.data?.frontmatter as Record<string, unknown> | undefined;\n    const unlisted = frontmatter?.unlisted;\n    if (typeof unlisted === \"boolean\") {\n      (file.data as Record<string, unknown>).unlisted = unlisted;\n    }\n  };\n};\n\nexport const UnlistedPages: QuartzTransformerPlugin<undefined> = () => {\n  return {\n    name: \"UnlistedPages\",\n    htmlPlugins(): PluggableList {\n      return [rehypeUnlisted()];\n    },\n  };\n};\n"]}

package/dist/types.d.ts

@@ -0,0 +1 @@
+export { BuildCtx, ProcessedContent, QuartzPluginData, QuartzTransformerPlugin, QuartzTransformerPluginInstance } from '@quartz-community/types';

package/dist/types.js

@@ -0,0 +1,3 @@
+
+//# sourceMappingURL=types.js.map
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"types.js"}

package/package.json

@@ -0,0 +1,98 @@
+{
+  "name": "@quartz-community/unlisted-pages",
+  "version": "0.1.0",
+  "description": "Bridges `frontmatter.unlisted` to `file.data.unlisted` so any page can opt out of discovery surfaces (contentIndex, RSS, sitemap, graph, explorer, search, backlinks, recent-notes, folder-page, tag-page) while remaining accessible by direct URL.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Quartz Community",
+  "homepage": "https://quartz.jzhao.xyz",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/quartz-community/unlisted-pages"
+  },
+  "keywords": [
+    "quartz",
+    "quartz-plugin",
+    "unlisted-pages",
+    "unlisted",
+    "hidden",
+    "rehype",
+    "hast",
+    "frontmatter"
+  ],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint . --max-warnings=0",
+    "format": "prettier . --check",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run typecheck && npm run lint && npm run format && npm run test",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "vfile": "^6.0.3"
+  },
+  "peerDependenciesMeta": {
+    "vfile": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@quartz-community/types": "^0.2.1",
+    "@quartz-community/utils": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/hast": "^3.0.4",
+    "@types/node": "^24.10.0",
+    "@typescript-eslint/eslint-plugin": "^7.18.0",
+    "@typescript-eslint/parser": "^7.18.0",
+    "eslint": "^8.57.0",
+    "eslint-config-prettier": "^9.1.0",
+    "prettier": "^3.6.2",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3",
+    "unified": "^11.0.5",
+    "vfile": "^6.0.3",
+    "vitest": "^2.1.9"
+  },
+  "quartz": {
+    "name": "unlisted-pages",
+    "displayName": "Unlisted Pages",
+    "category": "transformer",
+    "version": "1.0.0",
+    "quartzVersion": ">=5.0.0",
+    "dependencies": [],
+    "defaultOrder": 45,
+    "defaultEnabled": true,
+    "defaultOptions": {},
+    "optionSchema": {}
+  },
+  "engines": {
+    "node": ">=22",
+    "npm": ">=10.9.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}