@karaoke-cms/astro 0.6.1

package/src/themes/minimal/styles.css

@@ -0,0 +1,388 @@
+/* karaoke-cms minimal theme — serif, typography-first, warm */
+
+:root {
+  --font-body: Georgia, 'Times New Roman', serif;
+  --font-mono: ui-monospace, 'Cascadia Code', 'Fira Code', monospace;
+
+  --font-size-base: 1.125rem;
+  --font-size-sm:   0.9375rem;
+  --font-size-lg:   1.375rem;
+  --font-size-xl:   2rem;
+
+  --line-height-body:    1.75;
+  --line-height-heading: 1.2;
+
+  --color-bg:           #faf8f5;
+  --color-text:         #1c1917;
+  --color-muted:        #78716c;
+  --color-border:       #e7e5e4;
+  --color-link:         #92400e;
+  --color-link-hover:   #78350f;
+  --color-link-visited: #6b21a8;
+
+  --width-content: 620px;
+  --width-site:    720px;
+
+  --spacing-xs: 0.25rem;
+  --spacing-sm: 0.5rem;
+  --spacing-md: 1rem;
+  --spacing-lg: 2rem;
+  --spacing-xl: 4rem;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --color-bg:           #171310;
+    --color-text:         #e7e5e4;
+    --color-muted:        #a8a29e;
+    --color-border:       #292524;
+    --color-link:         #fb923c;
+    --color-link-hover:   #fdba74;
+    --color-link-visited: #c084fc;
+  }
+}
+
+*, *::before, *::after {
+  box-sizing: border-box;
+}
+
+html {
+  font-size: var(--font-size-base);
+}
+
+body {
+  margin: 0;
+  background: var(--color-bg);
+  color: var(--color-text);
+  font-family: var(--font-body);
+  line-height: var(--line-height-body);
+}
+
+/* --- Layout --- */
+
+.site-wrap {
+  max-width: var(--width-site);
+  margin: 0 auto;
+  padding: 0 var(--spacing-md);
+}
+
+/* --- Navigation --- */
+
+header {
+  border-bottom: 1px solid var(--color-border);
+  margin-bottom: var(--spacing-xl);
+}
+
+.header-inner {
+  max-width: var(--width-site);
+  margin: 0 auto;
+  padding: 0 var(--spacing-md);
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-lg);
+  height: 3rem;
+}
+
+.site-name {
+  font-weight: 700;
+  font-style: italic;
+  text-decoration: none;
+  color: var(--color-text);
+  flex-shrink: 0;
+  letter-spacing: -0.01em;
+}
+
+.site-name:hover {
+  color: var(--color-link);
+}
+
+header nav ul {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  gap: var(--spacing-md);
+}
+
+header nav ul a {
+  text-decoration: none;
+  color: var(--color-muted);
+  font-size: var(--font-size-sm);
+  font-family: var(--font-mono);
+  padding: var(--spacing-xs) 0;
+  min-height: 44px;
+  display: flex;
+  align-items: center;
+}
+
+header nav ul a:hover,
+header nav ul a[aria-current="page"] {
+  color: var(--color-text);
+}
+
+/* --- Page body (left + main + right regions) --- */
+
+.page-body {
+  display: flex;
+  align-items: flex-start;
+  max-width: var(--width-site);
+  margin: 0 auto;
+  padding: 0 var(--spacing-md);
+  min-height: calc(100vh - 12rem);
+  gap: var(--spacing-lg);
+}
+
+.page-body.has-left,
+.page-body.has-right {
+  max-width: calc(var(--width-site) + var(--width-sidebar, 220px) + var(--spacing-lg));
+}
+
+.page-body.has-left.has-right {
+  max-width: calc(var(--width-site) + 2 * (var(--width-sidebar, 220px) + var(--spacing-lg)));
+}
+
+main {
+  flex: 1;
+  min-width: 0;
+}
+
+.region-left,
+.region-right {
+  width: var(--width-sidebar, 220px);
+  flex-shrink: 0;
+  padding-top: var(--spacing-xs);
+}
+
+/* --- Sidebar --- */
+
+.sidebar-section {
+  margin-bottom: var(--spacing-lg);
+}
+
+.sidebar-heading {
+  font-size: var(--font-size-sm);
+  font-family: var(--font-mono);
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--color-muted);
+  margin: 0 0 var(--spacing-sm);
+}
+
+.sidebar-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-xs);
+}
+
+.sidebar-list li {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.sidebar-list a {
+  font-size: var(--font-size-sm);
+  text-decoration: none;
+  color: var(--color-text);
+}
+
+.sidebar-list a:hover {
+  color: var(--color-link);
+}
+
+/* --- Footer --- */
+
+footer {
+  border-top: 1px solid var(--color-border);
+  margin-top: var(--spacing-xl);
+  padding: var(--spacing-lg) var(--spacing-md);
+  max-width: var(--width-site);
+  margin-left: auto;
+  margin-right: auto;
+  color: var(--color-muted);
+  font-size: var(--font-size-sm);
+  font-family: var(--font-mono);
+}
+
+footer a {
+  color: var(--color-muted);
+}
+
+footer a:hover {
+  color: var(--color-link);
+}
+
+/* --- Typography --- */
+
+h1, h2, h3, h4 {
+  line-height: var(--line-height-heading);
+  margin-top: 0;
+  letter-spacing: -0.02em;
+}
+
+a {
+  color: var(--color-link);
+}
+
+a:hover {
+  color: var(--color-link-hover);
+}
+
+a:visited {
+  color: var(--color-link-visited);
+}
+
+code {
+  font-family: var(--font-mono);
+  font-size: 0.875em;
+  background: var(--color-border);
+  padding: 0.1em 0.3em;
+  border-radius: 2px;
+}
+
+pre {
+  background: var(--color-border);
+  padding: var(--spacing-md);
+  overflow-x: auto;
+  border-radius: 3px;
+}
+
+pre code {
+  background: none;
+  padding: 0;
+}
+
+/* --- Post/doc prose --- */
+
+.prose {
+  max-width: var(--width-content);
+}
+
+.prose img {
+  max-width: 100%;
+  height: auto;
+}
+
+/* --- Listing pages --- */
+
+.listing-header {
+  margin-bottom: var(--spacing-lg);
+}
+
+.listing-header h1 {
+  font-size: var(--font-size-xl);
+  margin-bottom: 0;
+}
+
+.post-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.post-list li {
+  padding: var(--spacing-sm) 0;
+  border-bottom: 1px solid var(--color-border);
+  display: flex;
+  gap: var(--spacing-md);
+  align-items: baseline;
+}
+
+.post-list li:first-child {
+  border-top: 1px solid var(--color-border);
+}
+
+.post-date {
+  color: var(--color-muted);
+  font-size: var(--font-size-sm);
+  font-family: var(--font-mono);
+  white-space: nowrap;
+  flex-shrink: 0;
+}
+
+.empty-state {
+  color: var(--color-muted);
+  padding: var(--spacing-lg) 0;
+}
+
+.empty-state p {
+  margin: 0 0 var(--spacing-sm);
+}
+
+/* --- Homepage two-column --- */
+
+.home-grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: var(--spacing-xl);
+}
+
+@media (max-width: 640px) {
+  .home-grid {
+    grid-template-columns: 1fr;
+    gap: var(--spacing-lg);
+  }
+
+  .page-body {
+    flex-direction: column;
+  }
+
+  .region-left,
+  .region-right {
+    width: 100%;
+  }
+}
+
+.home-section h2 {
+  font-size: var(--font-size-sm);
+  font-family: var(--font-mono);
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--color-muted);
+  margin-bottom: var(--spacing-md);
+}
+
+.home-section .post-list li {
+  flex-direction: column;
+  gap: var(--spacing-xs);
+}
+
+.view-all {
+  display: inline-block;
+  margin-top: var(--spacing-md);
+  font-size: var(--font-size-sm);
+  font-family: var(--font-mono);
+  color: var(--color-muted);
+}
+
+.view-all:hover {
+  color: var(--color-link);
+}
+
+/* --- Single post/doc --- */
+
+.post-header {
+  max-width: var(--width-content);
+  margin-bottom: var(--spacing-lg);
+}
+
+.post-header h1 {
+  font-size: var(--font-size-xl);
+  margin-bottom: var(--spacing-sm);
+}
+
+.post-meta {
+  color: var(--color-muted);
+  font-size: var(--font-size-sm);
+  font-family: var(--font-mono);
+}
+
+.post-footer {
+  margin-top: var(--spacing-xl);
+  padding-top: var(--spacing-md);
+  border-top: 1px solid var(--color-border);
+  max-width: var(--width-content);
+}

package/src/types.ts

@@ -0,0 +1,51 @@
+export type RegionComponent = 'header' | 'main-menu' | 'search' | 'recent-posts' | 'footer';
+
+export interface KaraokeConfig {
+  /** Site title — displayed in the browser tab and nav bar. Defaults to 'Karaoke'. */
+  title?: string;
+  /** Site description — used in RSS feed and OG meta tags. */
+  description?: string;
+  /** Theme name — must match a folder in themes/. Defaults to 'default'. */
+  theme?: string;
+  modules?: {
+    search?: { enabled?: boolean };
+    comments?: {
+      enabled?: boolean;
+      /** GitHub repo in "owner/repo" format */
+      repo?: string;
+      repoId?: string;
+      category?: string;
+      categoryId?: string;
+    };
+  };
+  layout?: {
+    regions?: {
+      top?:    { components?: RegionComponent[] };
+      left?:   { components?: RegionComponent[] };
+      right?:  { components?: RegionComponent[] };
+      bottom?: { components?: RegionComponent[] };
+    };
+  };
+}
+
+/** Resolved (defaults filled in) modules config — available at build time via virtual module. */
+export interface ResolvedModules {
+  search: { enabled: boolean };
+  comments: {
+    enabled: boolean;
+    repo: string;
+    repoId: string;
+    category: string;
+    categoryId: string;
+  };
+}
+
+/** Resolved (defaults filled in) layout config — available at build time via virtual module. */
+export interface ResolvedLayout {
+  regions: {
+    top:    { components: RegionComponent[] };
+    left:   { components: RegionComponent[] };
+    right:  { components: RegionComponent[] };
+    bottom: { components: RegionComponent[] };
+  };
+}

package/src/utils/resolve-layout.ts

@@ -0,0 +1,13 @@
+import type { KaraokeConfig, ResolvedLayout } from '../types.js';
+
+export function resolveLayout(config: KaraokeConfig | null | undefined): ResolvedLayout {
+  const regions = config?.layout?.regions;
+  return {
+    regions: {
+      top:    { components: regions?.top?.components    ?? ['header', 'main-menu', 'search'] },
+      left:   { components: regions?.left?.components   ?? [] },
+      right:  { components: regions?.right?.components  ?? [] },
+      bottom: { components: regions?.bottom?.components ?? ['footer'] },
+    },
+  };
+}

package/src/utils/resolve-modules.ts

@@ -0,0 +1,40 @@
+// Minimal config shape — mirrors KaraokeConfig.modules without importing from root
+// so this utility stays self-contained and testable.
+export interface ModuleConfig {
+  modules?: {
+    search?: { enabled?: boolean };
+    comments?: {
+      enabled?: boolean;
+      repo?: string;
+      repoId?: string;
+      category?: string;
+      categoryId?: string;
+    };
+  };
+}
+
+export interface ResolvedModules {
+  search: { enabled: boolean };
+  comments: {
+    enabled: boolean;
+    repo: string;
+    repoId: string;
+    category: string;
+    categoryId: string;
+  };
+}
+
+export function resolveModules(config: ModuleConfig | null | undefined): ResolvedModules {
+  return {
+    search: {
+      enabled: config?.modules?.search?.enabled ?? false,
+    },
+    comments: {
+      enabled: config?.modules?.comments?.enabled ?? false,
+      repo: config?.modules?.comments?.repo ?? '',
+      repoId: config?.modules?.comments?.repoId ?? '',
+      category: config?.modules?.comments?.category ?? '',
+      categoryId: config?.modules?.comments?.categoryId ?? '',
+    },
+  };
+}

package/src/validate-config.d.ts

@@ -0,0 +1,14 @@
+import type { KaraokeConfig } from './types.js';
+
+/**
+ * Resolve the active theme name from karaoke.config.
+ * Falls back to 'default' if config is absent.
+ * Throws a clear error if the named theme folder doesn't exist.
+ */
+export function getTheme(config: KaraokeConfig | null | undefined, themesDir: string): string;
+
+/**
+ * Validate module config at build time.
+ * Throws a clear error if comments is enabled but required fields are missing.
+ */
+export function validateModules(config: KaraokeConfig | null | undefined): void;

package/src/validate-config.js

@@ -0,0 +1,59 @@
+/**
+ * validate-config.js — karaoke.config helpers
+ *
+ * Extracted here so the logic is unit-testable separately from astro.config.mjs.
+ */
+
+import { readdirSync, statSync } from 'fs'
+import { join } from 'path'
+
+/**
+ * Resolve the active theme name from karaoke.config.
+ * Falls back to 'default' if config is absent.
+ * Throws a clear error if the named theme folder doesn't exist.
+ *
+ * @param {import('../karaoke.config').KaraokeConfig | null | undefined} config
+ * @param {string} themesDir - absolute path to the src/themes directory
+ * @returns {string} the resolved theme name
+ */
+/**
+ * Validate module config at build time.
+ * Throws a clear error if comments is enabled but required fields are missing.
+ *
+ * @param {import('../karaoke.config').KaraokeConfig | null | undefined} config
+ */
+export function validateModules(config) {
+  const comments = config?.modules?.comments
+  if (!comments?.enabled) return
+
+  const required = ['repo', 'repoId', 'category', 'categoryId']
+  const missing = required.filter(k => !comments[k])
+  if (missing.length > 0) {
+    throw new Error(
+      `karaoke-cms: modules.comments.enabled is true but the following required fields are missing: ` +
+      `${missing.join(', ')}. Get these values from https://giscus.app`
+    )
+  }
+}
+
+export function getTheme(config, themesDir) {
+  const theme = config?.theme ?? 'default'
+  let available
+  try {
+    available = readdirSync(themesDir)
+  } catch {
+    throw new Error(
+      `karaoke-cms: src/themes/ directory not found at ${themesDir} — is this a karaoke-cms repo?`
+    )
+  }
+  available = available.filter(d => {
+    try { return statSync(join(themesDir, d)).isDirectory() } catch { return false }
+  })
+  if (!available.includes(theme)) {
+    throw new Error(
+      `karaoke-cms: theme "${theme}" not found in src/themes/. ` +
+      `Available: ${available.join(', ')}`
+    )
+  }
+  return theme
+}