@riebeckite/plugin-taxonomy 0.0.6

package/dist/src/locations.d.ts

@@ -0,0 +1,14 @@
+import { type ContentLocationInput, type ContentPublicLocation, type Diagnostic } from "@riebeckite/core";
+import type { ResolvedTaxonomyOptions } from "./types.js";
+/**
+ * Public-location strategy for folder index notes.
+ *
+ * Core's default resolver collapses only the root `index` slug to `/`. When
+ * `folderIndexes` is enabled, a note at `<folder>/index.md` resolves to
+ * `/<folder>` instead of `/<folder>/index`, so each folder can own its index
+ * page. The chosen permalink is recorded in `metadata["taxonomy.folder"]`.
+ *
+ * The resolver never overwrites a location that another note already claims as
+ * its default permalink; it reports a diagnostic instead.
+ */
+export declare function resolveFolderIndexLocations(entries: readonly ContentLocationInput[], options: ResolvedTaxonomyOptions, diagnostics: Diagnostic[]): ContentPublicLocation[];

package/dist/src/options.d.ts

@@ -0,0 +1,13 @@
+import type { ResolvedTaxonomyOptions, TaxonomyOptions } from "./types.js";
+export declare const DEFAULT_TAXONOMY_TAGS_BASE_PATH = "/tags";
+export declare const DEFAULT_TAXONOMY_FOLDERS_BASE_PATH = "/folders";
+export declare const DEFAULT_TAXONOMY_MIN_ENTRIES = 1;
+export declare const DEFAULT_TAXONOMY_RELATED_LIMIT = 8;
+export declare const DEFAULT_TAXONOMY_FEED_LIMIT = 50;
+export declare const DEFAULT_TAXONOMY_CLASS_NAME = "rr-taxonomy";
+export declare const DEFAULT_TAXONOMY_DATA_ENDPOINT = "/taxonomy/index.json";
+/**
+ * Applies defaults to `TaxonomyOptions`. Pure and deterministic so the plugin
+ * resolves options once and reuses them for data, feeds, SEO, and locations.
+ */
+export declare function resolveTaxonomyOptions(options?: TaxonomyOptions): ResolvedTaxonomyOptions;

package/dist/src/pages.d.ts

@@ -0,0 +1,9 @@
+import type { ResolvedTaxonomyOptions, TaxonomyPage, TaxonomyTerm } from "./types.js";
+/**
+ * Renders a taxonomy listing page fragment. The fragment owns the listing and
+ * related-term navigation only; the Site's route and layout wrap it (see the
+ * README for the documented app-route wiring).
+ */
+export declare function renderTaxonomyPage(term: TaxonomyTerm, options: ResolvedTaxonomyOptions): TaxonomyPage;
+/** Renders only the related-term navigation for a tag term. */
+export declare function renderRelatedTerms(term: TaxonomyTerm, options: ResolvedTaxonomyOptions): string;

package/dist/src/seo.d.ts

@@ -0,0 +1,11 @@
+import type { ResolvedRiebeckiteConfig, SeoMetadata } from "@riebeckite/core";
+import type { TaxonomyTerm } from "./types.js";
+/**
+ * Builds SEO metadata for a taxonomy listing page.
+ *
+ * When a plugin provides the Core `seo` extension point (for example
+ * `@riebeckite/plugin-seo`), the metadata is delegated to it so titles,
+ * canonical URLs, and JSON-LD stay consistent with the rest of the site. A
+ * minimal fallback keeps the helper usable without an SEO provider.
+ */
+export declare function buildTaxonomySeo(config: ResolvedRiebeckiteConfig, term: TaxonomyTerm): SeoMetadata;

package/dist/src/slug.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Slugifies a raw taxonomy value into a URL/file path. Nested values keep their
+ * `/` separators, so `Guide/Intro` becomes `guide/intro`.
+ *
+ * ASCII segments are lowercased and reduced to `[a-z0-9]` with `-` separators.
+ * A segment that reduces to nothing (for example a Japanese tag, which loses
+ * every character under `strict` ASCII slugification) falls back to its
+ * percent-encoded text so distinct values never share a URL.
+ */
+export declare function slugifyTaxonomyValue(value: string): string;

package/dist/src/types.d.ts

@@ -0,0 +1,145 @@
+import type { ContentManifestEntry, SeoMetadata } from "@riebeckite/core";
+/** Feed formats the taxonomy plugin can generate per term. */
+export type TaxonomyFeedFormat = "rss" | "atom" | "json";
+/** A taxonomy grouping category. */
+export type TaxonomyKind = "tag" | "folder";
+/** Per-format feed output toggles. */
+export type TaxonomyFeedOptions = {
+    rss?: boolean;
+    atom?: boolean;
+    json?: boolean;
+};
+/** Options accepted by `taxonomy()`. */
+export type TaxonomyOptions = {
+    /** Generate tag terms. Defaults to `true`. */
+    tags?: boolean;
+    /** Generate folder terms. Defaults to `true`. */
+    folders?: boolean;
+    /** Site-local path prefix for tag pages. Defaults to `"/tags"`. */
+    tagsBasePath?: string;
+    /** Site-local path prefix for folder pages. Defaults to `"/folders"`. */
+    foldersBasePath?: string;
+    /** Folder grouping depth; `0` (or omitted) keeps the full folder path. */
+    folderDepth?: number;
+    /** Drop terms with fewer entries than this. Defaults to `1`. */
+    minEntries?: number;
+    /** Include related-term navigation for tag terms. Defaults to `true`. */
+    related?: boolean;
+    /** Maximum related terms per tag. Defaults to `8`. */
+    relatedLimit?: number;
+    /** Encode folder index notes (`<folder>/index.md`) as `<folder>`. Defaults to `false`. */
+    folderIndexes?: boolean;
+    /** Per-format feed generation. Defaults to RSS, Atom, and JSON. */
+    feeds?: TaxonomyFeedOptions;
+    /** Maximum entries included in a per-term feed. Defaults to `50`. */
+    feedLimit?: number;
+    /** Display title for a term. Defaults to `#value` for tags and the path for folders. */
+    resolveTitle?: (context: TaxonomyTermContext) => string;
+    /** Root CSS class used by the rendered page fragments. Defaults to `"rr-taxonomy"`. */
+    className?: string;
+    /** JSON data endpoint served for app routes and clients. Defaults to `"/taxonomy/index.json"`. */
+    dataEndpoint?: string;
+};
+/** `TaxonomyOptions` with every default resolved. */
+export type ResolvedTaxonomyOptions = {
+    tags: boolean;
+    folders: boolean;
+    tagsBasePath: string;
+    foldersBasePath: string;
+    folderDepth: number;
+    minEntries: number;
+    related: boolean;
+    relatedLimit: number;
+    folderIndexes: boolean;
+    feeds: Required<TaxonomyFeedOptions>;
+    feedLimit: number;
+    className: string;
+    dataEndpoint: string;
+    resolveTitle?: (context: TaxonomyTermContext) => string;
+};
+/** Context passed to a custom `resolveTitle`. */
+export type TaxonomyTermContext = {
+    kind: TaxonomyKind;
+    value: string;
+    basePath: string;
+};
+/** A lightweight entry reference safe to serialize into JSON data. */
+export type TaxonomyEntryReference = {
+    slug: string;
+    permalink: string;
+    title: string;
+    updated: string | null;
+    summary: string;
+};
+/** A related-term reference used by related-tag navigation. */
+export type TaxonomyRelatedTerm = {
+    kind: TaxonomyKind;
+    value: string;
+    title: string;
+    path: string;
+    permalink: string;
+    count: number;
+};
+/** Resolved feed URLs for one term. */
+export type TaxonomyFeedLinks = {
+    rss?: string;
+    atom?: string;
+    json?: string;
+};
+/** A single tag or folder listing. */
+export type TaxonomyTerm = {
+    kind: TaxonomyKind;
+    /** Raw grouping key (`"Guide/Intro"`, `"notes/sub"`). */
+    value: string;
+    /** Display title, `#value` for tags by default. */
+    title: string;
+    /** Site-local listing path, for example `/tags/guide/intro`. */
+    path: string;
+    /** Resolved entries, in manifest query order. */
+    entries: ContentManifestEntry[];
+    /** Related terms (tags only). */
+    related: TaxonomyRelatedTerm[];
+    /** Generated feed paths (site-local). */
+    feeds: TaxonomyFeedLinks;
+    /** Site-local feed file paths that the build emits. */
+    feedFiles: string[];
+};
+/** The complete tag and folder taxonomy for a manifest. */
+export type TaxonomyIndex = {
+    tags: TaxonomyTerm[];
+    folders: TaxonomyTerm[];
+};
+/** JSON-safe projection of a {@link TaxonomyTerm}. */
+export type TaxonomyTermData = {
+    kind: TaxonomyKind;
+    value: string;
+    title: string;
+    path: string;
+    permalink: string;
+    count: number;
+    entries: TaxonomyEntryReference[];
+    related: TaxonomyRelatedTerm[];
+    feeds: TaxonomyFeedLinks;
+};
+/** JSON-safe projection of a {@link TaxonomyIndex}. */
+export type TaxonomyIndexData = {
+    tags: TaxonomyTermData[];
+    folders: TaxonomyTermData[];
+};
+/** A rendered taxonomy listing page fragment. */
+export type TaxonomyPage = {
+    title: string;
+    /** `PostContent`-compatible frontmatter for the listing page. */
+    frontmatter: {
+        title: string;
+    };
+    html: string;
+    /** `entry.headTags`-compatible feed discovery links. */
+    headTags: TaxonomyHeadTag[];
+};
+/** Minimal head tag shape matching the Core `PluginHeadTag` contract. */
+export type TaxonomyHeadTag = {
+    tag: "link";
+    attrs: Record<string, string>;
+};
+export type { SeoMetadata };

package/dist/src/url.d.ts

@@ -0,0 +1,7 @@
+import type { ResolvedRiebeckiteConfig } from "@riebeckite/core";
+/**
+ * Resolves a site-local path against the configured site `baseUrl`. Mirrors the
+ * SEO plugin's absolute-URL convention so taxonomy feeds and metadata match the
+ * rest of the site without depending on the SEO package.
+ */
+export declare function buildTaxonomyAbsoluteUrl(config: ResolvedRiebeckiteConfig, pathOrUrl: string): string;

package/dist/src/xml.d.ts

@@ -0,0 +1 @@
+export declare function escapeTaxonomyXml(value: string): string;

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@riebeckite/plugin-taxonomy",
+  "version": "0.0.6",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "source": "./index.ts",
+      "default": "./dist/index.js"
+    },
+    "./style.css": "./style.css"
+  },
+  "dependencies": {
+    "@riebeckite/core": "0.0.6"
+  },
+  "devDependencies": {
+    "tsx": "^4.22.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "README_ja.md",
+    "dist",
+    "style.css"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Rerurate514/riebeckite.git",
+    "directory": "packages/plugins/taxonomy"
+  },
+  "homepage": "https://github.com/Rerurate514/riebeckite#readme",
+  "bugs": {
+    "url": "https://github.com/Rerurate514/riebeckite/issues"
+  },
+  "description": "Build-time tag and folder taxonomy data, per-term feeds, and SEO for Riebeckite.",
+  "keywords": [
+    "riebeckite",
+    "plugin",
+    "taxonomy",
+    "tags",
+    "feeds"
+  ],
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "sideEffects": [
+    "./style.css"
+  ],
+  "scripts": {
+    "build": "node ../../../scripts/build_package.mjs",
+    "test": "node --import tsx --test \"test/*.test.ts\""
+  }
+}

package/style.css

@@ -0,0 +1,107 @@
+.rr-taxonomy {
+  --rr-taxonomy-ink: var(--rb-color-ink, #1a1a1a);
+  --rr-taxonomy-muted: var(--rb-color-muted, #69645c);
+  --rr-taxonomy-rule: color-mix(
+    in srgb,
+    var(--rr-taxonomy-ink) 14%,
+    transparent
+  );
+  --rr-taxonomy-accent: var(--rb-color-accent, #b5460f);
+
+  color: var(--rr-taxonomy-ink);
+}
+
+.rr-taxonomy__title {
+  margin: 0 0 0.5rem;
+  font-size: 1.75rem;
+  line-height: 1.2;
+  letter-spacing: -0.01em;
+}
+
+.rr-taxonomy__count {
+  margin: 0 0 1.25rem;
+  color: var(--rr-taxonomy-muted);
+  font-size: 0.875rem;
+}
+
+.rr-taxonomy__feeds {
+  display: flex;
+  gap: 0.75rem;
+  margin-bottom: 1.25rem;
+  font-size: 0.8125rem;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+}
+
+.rr-taxonomy__feed {
+  color: var(--rr-taxonomy-accent);
+  text-decoration: none;
+  border-bottom: 1px solid var(--rr-taxonomy-rule);
+  padding-bottom: 0.1em;
+}
+
+.rr-taxonomy__feed:hover,
+.rr-taxonomy__feed:focus-visible {
+  border-bottom-color: currentColor;
+}
+
+.rr-taxonomy__list {
+  display: grid;
+  gap: 0.5rem;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.rr-taxonomy__item {
+  margin: 0;
+  padding-bottom: 0.5rem;
+  border-bottom: 1px solid var(--rr-taxonomy-rule);
+}
+
+.rr-taxonomy__link {
+  color: inherit;
+  text-decoration: none;
+}
+
+.rr-taxonomy__link:hover,
+.rr-taxonomy__link:focus-visible {
+  color: var(--rr-taxonomy-accent);
+}
+
+.rr-taxonomy__related {
+  margin-top: 2rem;
+  padding-top: 1rem;
+  border-top: 1px solid var(--rr-taxonomy-rule);
+}
+
+.rr-taxonomy__related ul {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.rr-taxonomy__related-link {
+  display: inline-block;
+  padding: 0.15rem 0.5rem;
+  color: var(--rr-taxonomy-ink);
+  text-decoration: none;
+  border: 1px solid var(--rr-taxonomy-rule);
+  border-radius: 999px;
+  font-size: 0.8125rem;
+}
+
+.rr-taxonomy__related-link:hover,
+.rr-taxonomy__related-link:focus-visible {
+  border-color: var(--rr-taxonomy-accent);
+  color: var(--rr-taxonomy-accent);
+}
+
+html[data-theme="dark"] .rr-taxonomy,
+html.dark .rr-taxonomy {
+  --rr-taxonomy-ink: var(--rb-color-paper, #ffffff);
+  --rr-taxonomy-muted: var(--rb-color-muted, #a8a29a);
+}