open-index/open-npm huggingface dataset:
npm package: @karaoke-cms/assert-privacy
Description: Post-build privacy gate for karaoke-cms
Latest version: 0.20.10

# @karaoke-cms/assert-privacy

Post-build privacy gate for karaoke-cms. Scans the built `dist/` directory and fails if any unpublished vault content has leaked into the output.

## Usage

Runs automatically as a CI step after `astro build`:

```yaml
# .github/workflows/deploy.yml
- run: npm run build
- run: node scripts/assert-privacy.js dist
```

Or manually:

```bash
node scripts/assert-privacy.js dist
```

## What it does

Walks every `.html` file in the build output and checks:

- No content from unpublished vault entries (those without `publish: true`) appears in any page
- The RSS feed at `dist/rss.xml` is well-formed XML
- No handbook content leaked into production HTML

Exits with code 1 and a clear error message if a violation is found, blocking the deploy.

## Status

**Stub** — the package placeholder is installed by scaffolded projects. The implementation lives at `scripts/assert-privacy.js` in your project directory.

## What's new in 0.9.5

No user-facing changes in this release — version bumped for lockstep with the monorepo.
npm package: @karaoke-cms/migrate
Description: Migrate a karaoke-cms fork-and-go repo to npm package model
Latest version: 0.9.0

# @karaoke-cms/migrate

Migration tool for karaoke-cms. Helps existing fork-and-go karaoke-cms repos adopt the npm package model.

## Where it belongs

`packages/migrate/` in the monorepo. Intended to run once in an existing project directory:

```bash
npx @karaoke-cms/migrate
```

## What it does

Planned: rewrites an existing fork-based project (where the framework code lived directly in `src/`) to the npm-package model (where all framework code is in `@karaoke-cms/astro` and a theme package).

Specific operations (to be implemented):

- Detects the existing framework version and structure
- Removes framework source files that are now owned by `@karaoke-cms/astro`
- Writes a `karaoke.config.ts` with equivalent settings derived from the old config
- Updates `astro.config.mjs` to use `karaoke()` instead of inline integration code
- Updates `src/content.config.ts` to use `makeCollections()`
- Preserves the vault content directory untouched

## Status

**Not yet implemented.** The package exists as a placeholder. The `bin/karaoke-migrate` entry is declared but `src/` is empty.

The migration path from fork-and-go to npm-package model is documented manually in the project wiki.

## How it changes the behavior of the system

This package does not affect running sites. It is a one-time migration tool that changes the project structure so the site can thereafter be maintained by upgrading `@karaoke-cms/astro` and the theme packages rather than pulling framework changes manually.
npm package: @karaoke-cms/module-comments
Description: Giscus comments module for karaoke-cms
Latest version: 0.20.10

# @karaoke-cms/module-comments

Giscus comments module for karaoke-cms. Embeds GitHub Discussion threads on blog posts and docs pages.

## Installation

```bash
pnpm add @karaoke-cms/module-comments
```

## Usage

```ts
// karaoke.config.ts
import { defineConfig } from '@karaoke-cms/astro';
import { comments } from '@karaoke-cms/module-comments';

export default defineConfig({
  modules: [
    comments({
      repo: 'owner/repo',
      repoId: 'R_...',
      category: 'General',
      categoryId: 'DIC_...',
    }),
  ],
});
```

Get `repoId` and `categoryId` from [giscus.app](https://giscus.app) after enabling GitHub Discussions on your repository.

## Per-post override

Individual posts and docs can disable comments via frontmatter:

```yaml
---
title: My Post
comments: false
---
```

## What's new in 0.18.2

No user-facing changes in this release.

## CSS contract

Themes must implement the `.comments` class:

| Class | Description | Required |
|-------|-------------|----------|
| `comments` | Comments section wrapper (Giscus embed) | Yes |
npm package: @karaoke-cms/module-search
Description: Pagefind search module for karaoke-cms
Latest version: 0.20.10

# @karaoke-cms/module-search

Pagefind search module for karaoke-cms — full-text search at `/search`, powered by [Pagefind](https://pagefind.app). Add it once; the search index is generated automatically at build time.

## Installation

```bash
npm install @karaoke-cms/module-search
```

## Usage

```ts
// karaoke.config.ts
import { defineConfig } from '@karaoke-cms/astro';
import { search } from '@karaoke-cms/module-search';

export default defineConfig({
  // ...
  modules: [search()],
});
```

No options required. The module injects a `/search` page and runs the Pagefind indexer automatically after `npm run build`.

## How it works

1. You add `search()` to `modules[]`.
2. On `npm run build`, the module runs `npx pagefind --site dist/` as a post-build hook — no CI changes needed.
3. The `/search` page renders the Pagefind widget, which loads the pre-built index client-side.

### Dev mode

After running `npm run build` at least once, the search index in `dist/pagefind/` is automatically served at `/pagefind/` during `npm run dev` via a Vite middleware. Search works in dev without restarting the dev server — just build once to generate the index, then use dev as normal.

## Routes

| Pattern | Description |
|---------|-------------|
| `/search` | Search UI page — Pagefind widget |

## Default CSS

The module ships default styles for the search page. On first dev run, `src/styles/search.css` is copied to your project and imported automatically. You can edit this file to customise the layout.

## What's new in 0.18.2

No user-facing changes in this release.

## What's new in 0.17.0

- **Search works in dev mode** — after running `npm run build` once, `dist/pagefind/` is served at `/pagefind/` by a Vite dev middleware. No dev server restart needed; search results appear immediately in `npm run dev`.

## What's new in 0.13.1

No user-facing changes in this release.

## What's new in 0.13.0

- **Initial release** — `/search` page with Pagefind widget; Pagefind index generated automatically at `astro:build:done`; default CSS shipped with the module
npm package: @karaoke-cms/module-tags
Description: Tags module for karaoke-cms — cross-collection tag index with per-tag RSS feeds
Latest version: 0.20.10

# @karaoke-cms/module-tags

Tags module for karaoke-cms — cross-collection tag index with per-tag RSS feeds. Aggregates tags from your blog and all active docs sections automatically.

## Installation

```bash
npm install @karaoke-cms/module-tags
```

## Usage

```ts
// karaoke.config.ts
import { defineConfig } from '@karaoke-cms/astro';
import { tags } from '@karaoke-cms/module-tags';

export default defineConfig({
  // ...
  modules: [tags()],
});
```

No options required. Once added, your site gets `/tags`, `/tags/[tag]`, and `/tags/[tag]/rss.xml` automatically.

## Configuration

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `mount` | `string` | `'/tags'` | URL prefix for all tag routes |
| `enabled` | `boolean` | `true` | Set `false` to disable without removing from config |

## Routes

| Pattern | Description |
|---------|-------------|
| `/tags` | All-tags listing — every tag with post count |
| `/tags/[tag]` | Posts and docs matching a single tag |
| `/tags/[tag]/rss.xml` | RSS feed for a single tag |

## Frontmatter

Tags are read from the `tags` field on blog posts and docs pages:

```yaml
---
title: My Post
publish: true
tags: [javascript, tutorial]
---
```

No additional frontmatter fields are added by this module.

## What's new in 0.18.2

No user-facing changes in this release.

## What's new in 0.18.0

- **Dynamic content source indexing** — the tags module now discovers and indexes all enabled content sources (blog and every active docs section) automatically, instead of querying a hardcoded blog collection. Adding or removing modules updates the tag index without any config changes.

## What's new in 0.13.1

No user-facing changes in this release.

## What's new in 0.13.0

- **Initial release** — `/tags`, `/tags/[tag]`, and per-tag RSS feeds; aggregates tags from blog and all active docs sections automatically; `mount` and `enabled` options
npm package: @karaoke-cms/theme-base
Description: Base CSS layer for karaoke-cms themes — resets, layout primitives, and structural styles
Latest version: 0.20.10

# @karaoke-cms/theme-base

Shared CSS foundation for karaoke-cms themes. Provides design tokens, resets, typography, layout primitives, and structural component styles that all themes build on top of.

Theme authors import the CSS layers and override tokens — no need to rewrite boilerplate layout or reset styles.

## Installation

```bash
npm install @karaoke-cms/theme-base
```

## Usage

In your theme's main CSS file:

```css
@import '@karaoke-cms/theme-base/tokens.css';
@import '@karaoke-cms/theme-base/base.css';

/* Override tokens */
:root {
    --font-size-base: 1.0625rem;
    --color-accent: #6366f1;
}

/* Add theme-specific styles */
```

## Exports

| Export | Description |
|--------|-------------|
| `./tokens.css` | Default CSS custom property values (colors, spacing, typography) |
| `./base.css` | Structural layout, resets, typography, component styles |
| `./styles-astro.css` | Combined Astro-aware stylesheet |
| `.` (JS) | `tokensCssPath` and `baseCssPath` — absolute file paths for programmatic use |

## What's new in 0.19.0

- New package — extracted from inline theme styles
- Design tokens as CSS custom properties (`--color-*`, `--font-*`, `--spacing-*`, `--width-*`)
- Structural styles: page-body grid, sidebar regions, prose, listings, tags, navigation
- Responsive breakpoints included
npm package: @karaoke-cms/theme-blog
Description: Blog theme for karaoke-cms — editorial layout with featured hero, card grid, and cover images
Latest version: 0.20.10

# @karaoke-cms/theme-blog

Editorial blog theme for karaoke-cms — featured hero post, card grid, and cover image support. Blog-only: no docs or knowledge-base routes.

## Installation

```bash
npm install @karaoke-cms/theme-blog
```

## Usage

```ts
// karaoke.config.ts
import { defineConfig } from '@karaoke-cms/astro';
import { loadEnv } from '@karaoke-cms/astro/env';

const env = loadEnv(new URL('.', import.meta.url));

export default defineConfig({
  vault: env.KARAOKE_VAULT,
  title: 'My Blog',
  // theme-blog uses the legacy integration API — import the default export
  // and register it directly in astro.config.mjs
});
```

> **Note:** `theme-blog` currently uses the legacy theme API and does not yet expose a `themeBlog()` factory. Register it in `astro.config.mjs`:
>
> ```js
> // astro.config.mjs
> import { defineConfig } from 'astro/config';
> import karaoke from '@karaoke-cms/astro';
> import themeBlog from '@karaoke-cms/theme-blog';
> import karaokeConfig from './karaoke.config.ts';
>
> export default defineConfig({
>   site: 'https://your-site.pages.dev',
>   integrations: [karaoke({ ...karaokeConfig, theme: themeBlog })],
> });
> ```

## Routes

| Route | Description |
|-------|-------------|
| `/` | Home — featured hero post + recent posts grid |
| `/blog` | All published posts |
| `/blog/[slug]` | Post page with cover image |
| `/tags` | Tags index |
| `/tags/[tag]` | Posts by tag |
| `/404` | Not found page |

No `/docs` routes — use `theme-default` for mixed blog + docs sites.

## Extended frontmatter

Pass `blogThemeExtension` to `makeCollections()` to unlock cover image and featured-post fields:

```ts
// src/content.config.ts
import { makeCollections, blogThemeExtension } from '@karaoke-cms/astro/collections';
import { loadEnv } from '@karaoke-cms/astro/env';

const env = loadEnv(new URL('..', import.meta.url));
export const collections = makeCollections(
  new URL('..', import.meta.url),
  env.KARAOKE_VAULT,
  { blogSchema: blogThemeExtension },
);
```

Extra fields (all optional):

| Field | Type | Description |
|-------|------|-------------|
| `cover_image` | `string` | Path or URL to the post's cover image |
| `featured` | `boolean` | Pin this post as the hero on the home page |
| `abstract` | `string` | Override the description shown in cards and the hero |

## Design system

Tokens on `:root`: `--font-body`, `--font-mono`, `--color-bg`, `--color-text`, `--color-muted`, `--color-card-bg`, `--color-hero-overlay`, `--width-content` (700px), `--width-site` (1100px), `--radius-card` (8px). Dark mode via `@media (prefers-color-scheme: dark)`.

## What's new in 0.17.0

No user-facing changes in this release.

## What's new in 0.9.5

No user-facing changes in this release — version bumped for lockstep with the monorepo.
npm package: @karaoke-cms/theme-minimal
Description: Minimal theme for karaoke-cms
Latest version: 0.20.10

# @karaoke-cms/theme-minimal

Minimal CSS-only theme for karaoke-cms. Pure typography and spacing — no sidebar, no card grids, no decorative elements.

## Status

**Not yet implemented.** The package exists as a placeholder. Use `@karaoke-cms/theme-default` or `@karaoke-cms/theme-blog` for active themes.

## Planned

When implemented: same routes as `theme-default` but with a single-column layout, system font stack, and a small CSS file. No JavaScript, no images, no web fonts.

## What's new in 0.9.5

No user-facing changes in this release — version bumped for lockstep with the monorepo.
npm package: @karaoke-cms/vault
Description: Obsidian vault path resolution, collection layout, and markdown frontmatter schemas — framework-agnostic core for karaoke-cms
Latest version: 0.20.10

# @karaoke-cms/vault

Framework-agnostic helpers for Obsidian vault layout and frontmatter — shared by `@karaoke-cms/astro`, `@karaoke-cms/enrich`, and any other Node tooling.

## Exports

- **Paths** — `resolveVaultDir`, `getBlogFolderFromConfig`, `vaultJoin`, `computeAllCollectionBases`, `getEnrichContentRoots`
- **Glob exclusion** — `excludeGlobPatternsForBase`, `excludePrefixesForBase`
- **Schemas** — `vaultBaseSchema`, `vaultRelaxedSchema`, `blogThemeExtension`, `validateEnrichFrontmatter`
- **Menus** — `resolveMenus(vaultDir, modules?)` parses `{vault}/_website/menus.yaml` and merges module menu entries (same behavior as the site build)

Import from `@karaoke-cms/vault`. `@karaoke-cms/astro` re-exports `resolveMenus` from `src/utils/resolve-menus.ts` for existing import paths.

## What's new in 0.18.2

- **`.ts` import extensions** -- internal imports changed from `.js` to `.ts` extensions for native ESM compatibility. If you import from `@karaoke-cms/vault` subpaths, no changes are needed -- this only affects the package internals.

## Dependency rule

Depends on `@karaoke-cms/contracts`, `yaml`, and `zod` only — **not** on `@karaoke-cms/astro`.