mkdnsite 0.0.1 → 1.1.0

package/src/config/schema.ts

@@ -28,11 +28,131 @@ export interface MkdnSiteConfig {
   /** Client-side enhancement modules */
   client: ClientConfig
 
+  /**
+   * Preset that configures sensible defaults for common use cases.
+   * Applied before user config — any explicit user setting overrides the preset.
+   * - 'docs': nav + TOC + prev/next (default-like, best for documentation sites)
+   * - 'blog': page title + date + reading time + prev/next, no nav sidebar
+   */
+  preset?: 'docs' | 'blog'
+
   /** Markdown renderer engine (default: 'portable') */
   renderer: RendererEngine
 
   /** Static files directory for images, videos, etc. */
   staticDir?: string
+
+  /**
+   * Glob patterns to include. Only matching files will be served.
+   * Mutually exclusive with `exclude` — define one or the other, not both.
+   * e.g. ['docs', 'guides/*.md']
+   */
+  include?: string[]
+
+  /**
+   * Glob patterns to exclude. Matching files will not be served.
+   * Mutually exclusive with `include` — define one or the other, not both.
+   * e.g. ['private', '*.draft.md']
+   */
+  exclude?: string[]
+
+  /** GitHub repository source (alternative to local contentDir) */
+  github?: import('../content/types.ts').GitHubSourceConfig
+
+  /** MCP (Model Context Protocol) server configuration */
+  mcp: McpConfig
+
+  /** Analytics configuration (disabled by default) */
+  analytics?: AnalyticsConfig
+
+  /** Content Security Policy configuration */
+  csp?: CspConfig
+
+  /** Response caching and CDN header configuration */
+  cache?: CacheConfig
+}
+
+/** MCP (Model Context Protocol) server configuration */
+export interface McpConfig {
+  /** Enable the built-in MCP server (default: true) */
+  enabled: boolean
+  /** MCP endpoint path (default: '/mcp') */
+  endpoint?: string
+}
+
+/** Content Security Policy configuration */
+export interface CspConfig {
+  /** Enable the Content-Security-Policy header on HTML responses (default: true) */
+  enabled: boolean
+  /** Additional script-src sources */
+  extraScriptSrc?: string[]
+  /** Additional style-src sources */
+  extraStyleSrc?: string[]
+  /** Additional img-src sources */
+  extraImgSrc?: string[]
+  /** Additional connect-src sources */
+  extraConnectSrc?: string[]
+  /** Additional font-src sources */
+  extraFontSrc?: string[]
+  /** Report URI for CSP violation reports */
+  reportUri?: string
+}
+
+/** Response caching and CDN header configuration */
+export interface CacheConfig {
+  /** Enable response caching (default: false — opt-in) */
+  enabled?: boolean
+  /** Cache-Control max-age in seconds for HTML responses (default: 300) */
+  maxAge?: number
+  /** Cache-Control max-age in seconds for markdown responses (default: 300) */
+  maxAgeMarkdown?: number
+  /** stale-while-revalidate in seconds (default: 0, meaning omitted) */
+  staleWhileRevalidate?: number
+  /** Version tag for ETag and CDN cache busting (e.g. 'v1.2.3' or git SHA) */
+  versionTag?: string
+}
+
+/** Analytics configuration */
+export interface AnalyticsConfig {
+  /** Google Analytics 4 (GA4) configuration */
+  googleAnalytics?: {
+    /** GA4 measurement ID, e.g. 'G-XXXXXXXXXX' */
+    measurementId: string
+  }
+  /** Server-side traffic analytics (default: disabled) */
+  traffic?: TrafficAnalyticsConfig
+}
+
+/** Server-side traffic analytics configuration */
+export interface TrafficAnalyticsConfig {
+  /**
+   * Enable server-side traffic analytics.
+   * When false (default) the analytics hook is skipped entirely.
+   */
+  enabled?: boolean
+  /**
+   * Log each request as a JSON line to stdout.
+   * Useful for development / debugging. Requires enabled: true.
+   */
+  console?: boolean
+}
+
+/** OpenGraph / social sharing meta tag configuration */
+export interface OgConfig {
+  /** Default OG image URL (can be overridden per-page via frontmatter `og_image`) */
+  image?: string
+  /** Default OG type (default: 'website' for index, 'article' for other pages) */
+  type?: string
+  /** Twitter card type: 'summary' or 'summary_large_image' (default: 'summary') */
+  twitterCard?: 'summary' | 'summary_large_image'
+  /** Twitter @handle for the site (e.g. '@mkdnsite') */
+  twitterSite?: string
+}
+
+/** Favicon configuration */
+export interface FaviconConfig {
+  /** Path or URL to the favicon file (.ico, .png, .svg) */
+  src: string
 }
 
 export interface SiteConfig {
@@ -40,6 +160,10 @@ export interface SiteConfig {
   description?: string
   url?: string
   lang?: string
+  /** OpenGraph / social sharing meta tag configuration */
+  og?: OgConfig
+  /** Favicon configuration */
+  favicon?: FaviconConfig
 }
 
 export interface ServerConfig {
@@ -47,6 +171,52 @@ export interface ServerConfig {
   hostname: string
 }
 
+/** CSS color token overrides for the built-in theme */
+export interface ColorTokens {
+  /** Primary accent color (links, highlights) */
+  accent?: string
+  /** Main text color */
+  text?: string
+  /** Muted text color */
+  textMuted?: string
+  /** Page background color */
+  bg?: string
+  /** Alternate background (nav, code blocks) */
+  bgAlt?: string
+  /** Border color */
+  border?: string
+  /** Link color */
+  link?: string
+  /** Link hover color */
+  linkHover?: string
+  /** Inline code background */
+  codeBg?: string
+  /** Code block (pre) background */
+  preBg?: string
+}
+
+/** Font stack overrides for the built-in theme */
+export interface FontTokens {
+  /** Body/prose font stack */
+  body?: string
+  /** Monospace font stack */
+  mono?: string
+  /** Heading font stack (defaults to body font) */
+  heading?: string
+}
+
+/** Logo image configuration */
+export interface LogoConfig {
+  /** Path or URL to the logo image */
+  src: string
+  /** Alt text for the logo image */
+  alt?: string
+  /** Logo display width in pixels (default: 32) */
+  width?: number
+  /** Logo display height in pixels (default: 32) */
+  height?: number
+}
+
 export interface ThemeConfig {
   /**
    * Rendering mode for markdown content.
@@ -58,9 +228,48 @@ export interface ThemeConfig {
   /** Custom React components to override default element rendering */
   components?: ComponentOverrides
 
-  /** Custom CSS file path or URL to use instead of default theme */
+  /**
+   * Inline CSS string appended after the built-in theme styles.
+   * Use this for small tweaks. For full replacement, set builtinCss: false.
+   */
   customCss?: string
 
+  /** URL to an external stylesheet loaded via <link rel="stylesheet"> */
+  customCssUrl?: string
+
+  /**
+   * Include the built-in theme CSS. Set to false to strip all default
+   * styles and start from a blank slate. (default: true)
+   */
+  builtinCss?: boolean
+
+  /** Light mode CSS color token overrides */
+  colors?: ColorTokens
+
+  /** Dark mode CSS color token overrides */
+  colorsDark?: ColorTokens
+
+  /** Font stack overrides */
+  fonts?: FontTokens
+
+  /** Logo image displayed in the nav header */
+  logo?: LogoConfig
+
+  /** Site name / text logo displayed in the nav header */
+  logoText?: string
+
+  /** Render page title from frontmatter as <h1> above article content */
+  pageTitle?: boolean
+
+  /** Render publish/update date from frontmatter below the page title */
+  pageDate?: boolean
+
+  /** Show prev/next page navigation links at the bottom of the article */
+  prevNext?: boolean
+
+  /** Show estimated reading time near the page date */
+  readingTime?: boolean
+
   /** Show navigation sidebar */
   showNav: boolean
 
@@ -74,7 +283,7 @@ export interface ThemeConfig {
   colorScheme: 'system' | 'light' | 'dark'
 
   /** Syntax highlighting theme for Shiki */
-  syntaxTheme: string
+  syntaxTheme?: string
 
   /** Dark mode syntax highlighting theme */
   syntaxThemeDark?: string
@@ -125,6 +334,9 @@ export interface ClientConfig {
 
   /** Enable client-side search (default: true when client enabled) */
   search: boolean
+
+  /** Enable Chart.js chart rendering (default: true when client enabled) */
+  charts: boolean
 }
 
 /**

package/src/content/assets.ts

@@ -0,0 +1,202 @@
+import { parseFrontmatter } from './frontmatter.ts'
+import type { ContentSource, ContentPage, NavNode } from './types.ts'
+import type { ContentCache } from './cache.ts'
+import { MemoryContentCache } from './cache.ts'
+import { buildNavTree } from './nav-builder.ts'
+
+interface ParsedFile {
+  path: string
+  meta: Record<string, unknown>
+  body: string
+  raw: string
+}
+
+export interface AssetsSourceConfig {
+  /** Workers Static Assets Fetcher binding */
+  assets: AssetsFetcher
+  /** Explicit list of .md file paths (if _manifest.json is not available) */
+  manifest?: string[]
+  /** Optional cache layer (defaults to in-memory). Pass KVContentCache for durable caching. */
+  cache?: ContentCache
+}
+
+// ─── Workers Static Assets type stub ─────────────────────────────────────────
+
+interface AssetsFetcher {
+  fetch: (input: Request | string) => Promise<Response>
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function slugToRelKey (slug: string): string {
+  const stripped = slug.replace(/^\/+|\.md$/g, '').replace(/\/+$/, '')
+  return stripped === '' ? 'index' : stripped
+}
+
+// ─── AssetsSource ────────────────────────────────────────────────────────────
+
+/**
+ * Content source that reads .md files from Cloudflare Workers Static Assets.
+ *
+ * Workers Static Assets are deployed alongside the Worker via wrangler deploy.
+ * Since the ASSETS binding doesn't support directory listing, a manifest of
+ * .md file paths is required. The manifest can be provided via:
+ *
+ * 1. A `_manifest.json` file in the assets directory (auto-discovered)
+ * 2. An explicit `manifest` array in the config
+ *
+ * Generate a manifest with:
+ *   find content -name '*.md' -printf '%P\n' | sort | jq -R -s 'split("\n") | map(select(. != ""))' > content/_manifest.json
+ *
+ * Or use the helper:
+ *   npx mkdnsite manifest --dir content > content/_manifest.json
+ */
+export class AssetsSource implements ContentSource {
+  private readonly assets: AssetsFetcher
+  private readonly explicitManifest: string[] | null
+  private readonly cache: ContentCache
+
+  private rawCache: Map<string, ParsedFile> | null = null
+  private rawCacheExpiresAt: number = 0
+  private initPromise: Promise<Map<string, ParsedFile>> | null = null
+
+  constructor (config: AssetsSourceConfig) {
+    this.assets = config.assets
+    this.explicitManifest = config.manifest ?? null
+    this.cache = config.cache ?? new MemoryContentCache()
+  }
+
+  // ─── Public API ────────────────────────────────────────────────────────────
+
+  async getPage (slug: string): Promise<ContentPage | null> {
+    const key = slugToRelKey(slug)
+
+    // Try cache first
+    for (const candidate of [key, key + '/index', key + '/README', key + '/readme']) {
+      const cached = await this.cache.getPage(candidate)
+      if (cached != null) return cached
+    }
+
+    // Fall through to prefetch
+    const pages = await this.ensurePrefetched()
+
+    for (const candidate of [key, key + '/index', key + '/README', key + '/readme']) {
+      const file = pages.get(candidate)
+      if (file != null && file.meta.draft !== true) {
+        const page = this.toContentPage(file)
+        await this.cache.setPage(candidate, page)
+        return page
+      }
+    }
+    return null
+  }
+
+  async getNavTree (): Promise<NavNode> {
+    const cached = await this.cache.getNav()
+    if (cached != null) return cached
+
+    const pages = await this.ensurePrefetched()
+    const files = Array.from(pages.values())
+    const nav = buildNavTree(files)
+    await this.cache.setNav(nav)
+    return nav
+  }
+
+  async listPages (): Promise<ContentPage[]> {
+    const cached = await this.cache.getPageList()
+    if (cached != null) return cached
+
+    const pages = await this.ensurePrefetched()
+    const result = Array.from(pages.values())
+      .filter(f => f.meta.draft !== true)
+      .map(f => this.toContentPage(f))
+    await this.cache.setPageList(result)
+    return result
+  }
+
+  async refresh (): Promise<void> {
+    this.rawCache = null
+    this.rawCacheExpiresAt = 0
+    this.initPromise = null
+    await this.cache.clear()
+  }
+
+  // ─── Internal ──────────────────────────────────────────────────────────────
+
+  private async ensurePrefetched (): Promise<Map<string, ParsedFile>> {
+    if (this.rawCache != null && Date.now() < this.rawCacheExpiresAt) {
+      return this.rawCache
+    }
+    if (this.initPromise != null) return await this.initPromise
+    this.initPromise = this.prefetchAll()
+    const result = await this.initPromise
+    this.initPromise = null
+    return result
+  }
+
+  private async getManifest (): Promise<string[]> {
+    if (this.explicitManifest != null) return this.explicitManifest
+
+    // Try to fetch _manifest.json from static assets
+    try {
+      const response = await this.assets.fetch(new Request('http://assets/_manifest.json'))
+      if (response.ok) {
+        const manifest = await response.json() as string[]
+        if (Array.isArray(manifest)) return manifest
+      }
+    } catch {
+      // manifest not available
+    }
+
+    throw new Error(
+      'AssetsSource: No manifest found. Create a _manifest.json file listing your .md paths, ' +
+      'or pass a manifest array to AssetsSourceConfig.'
+    )
+  }
+
+  private async prefetchAll (): Promise<Map<string, ParsedFile>> {
+    const manifest = await this.getManifest()
+    const mdPaths = manifest.filter(p => p.endsWith('.md'))
+
+    const fetched = await Promise.all(
+      mdPaths.map(async (filePath) => {
+        try {
+          const response = await this.assets.fetch(new Request(`http://assets/${filePath}`))
+          if (!response.ok) return null
+          const raw = await response.text()
+          const { meta, body } = parseFrontmatter(raw)
+          return { path: filePath, meta: meta as Record<string, unknown>, body, raw } satisfies ParsedFile
+        } catch {
+          return null
+        }
+      })
+    )
+
+    const pages = new Map<string, ParsedFile>()
+    for (const file of fetched) {
+      if (file == null) continue
+      const key = file.path.replace(/\.md$/, '')
+      pages.set(key, file)
+    }
+
+    this.rawCache = pages
+    this.rawCacheExpiresAt = Date.now() + 5 * 60 * 1000
+    return pages
+  }
+
+  private toContentPage (file: ParsedFile): ContentPage {
+    const key = file.path.replace(/\.md$/, '')
+    const isIndex = /(?:^|\/)(?:index|README|readme)$/.test(key)
+    const cleanKey = isIndex
+      ? key.replace(/\/(?:index|README|readme)$/, '')
+      : key
+    const slug = cleanKey === '' || cleanKey === 'index' ? '/' : '/' + cleanKey
+    return {
+      slug,
+      sourcePath: file.path,
+      meta: file.meta,
+      body: file.body,
+      raw: file.raw
+    }
+  }
+}

package/src/content/cache.ts

@@ -0,0 +1,232 @@
+import type { ContentPage, NavNode } from './types.ts'
+
+/**
+ * Content cache interface.
+ *
+ * Implementations:
+ * - MemoryContentCache: in-memory Map with TTL (default)
+ * - KVContentCache: Cloudflare KV-backed with TTL
+ */
+export interface ContentCache {
+  getPage: (key: string) => Promise<ContentPage | null>
+  setPage: (key: string, page: ContentPage) => Promise<void>
+
+  getNav: () => Promise<NavNode | null>
+  setNav: (nav: NavNode) => Promise<void>
+
+  getPageList: () => Promise<ContentPage[] | null>
+  setPageList: (pages: ContentPage[]) => Promise<void>
+
+  /** Get serialized search index JSON (null if not cached) */
+  getSearchIndex: () => Promise<string | null>
+  /** Store serialized search index JSON */
+  setSearchIndex: (data: string) => Promise<void>
+
+  clear: () => Promise<void>
+}
+
+// ─── In-Memory Implementation ────────────────────────────────────────────────
+
+interface CacheEntry<T> {
+  value: T
+  expiresAt: number
+}
+
+const DEFAULT_TTL_MS = 5 * 60 * 1000 // 5 minutes
+
+export class MemoryContentCache implements ContentCache {
+  private readonly pages = new Map<string, CacheEntry<ContentPage>>()
+  private nav: CacheEntry<NavNode> | null = null
+  private pageList: CacheEntry<ContentPage[]> | null = null
+  private searchIndex: CacheEntry<string> | null = null
+  private readonly ttlMs: number
+
+  constructor (ttlMs?: number) {
+    this.ttlMs = ttlMs ?? DEFAULT_TTL_MS
+  }
+
+  async getPage (key: string): Promise<ContentPage | null> {
+    const entry = this.pages.get(key)
+    if (entry != null && Date.now() < entry.expiresAt) return entry.value
+    return null
+  }
+
+  async setPage (key: string, page: ContentPage): Promise<void> {
+    this.pages.set(key, { value: page, expiresAt: Date.now() + this.ttlMs })
+  }
+
+  async getNav (): Promise<NavNode | null> {
+    if (this.nav != null && Date.now() < this.nav.expiresAt) return this.nav.value
+    return null
+  }
+
+  async setNav (nav: NavNode): Promise<void> {
+    this.nav = { value: nav, expiresAt: Date.now() + this.ttlMs }
+  }
+
+  async getPageList (): Promise<ContentPage[] | null> {
+    if (this.pageList != null && Date.now() < this.pageList.expiresAt) return this.pageList.value
+    return null
+  }
+
+  async setPageList (pages: ContentPage[]): Promise<void> {
+    this.pageList = { value: pages, expiresAt: Date.now() + this.ttlMs }
+  }
+
+  async getSearchIndex (): Promise<string | null> {
+    if (this.searchIndex != null && Date.now() < this.searchIndex.expiresAt) {
+      return this.searchIndex.value
+    }
+    return null
+  }
+
+  async setSearchIndex (data: string): Promise<void> {
+    this.searchIndex = { value: data, expiresAt: Date.now() + this.ttlMs }
+  }
+
+  async clear (): Promise<void> {
+    this.pages.clear()
+    this.nav = null
+    this.pageList = null
+    this.searchIndex = null
+  }
+}
+
+// ─── Cloudflare KV Implementation ────────────────────────────────────────────
+
+interface KVNamespace {
+  get: (key: string) => Promise<string | null>
+  put: (key: string, value: string, options?: { expirationTtl?: number }) => Promise<void>
+  delete: (key: string) => Promise<void>
+  list: (options?: { prefix?: string }) => Promise<{ keys: Array<{ name: string }> }>
+}
+
+const DEFAULT_KV_TTL_SECONDS = 300 // 5 minutes
+
+/**
+ * Cloudflare KV-backed content cache.
+ *
+ * Serializes ContentPage and NavNode to JSON and stores in KV with TTL.
+ * Falls through to in-memory cache for hot-path performance within
+ * a single Worker isolate, with KV as the shared durable layer.
+ */
+export class KVContentCache implements ContentCache {
+  private readonly kv: KVNamespace
+  private readonly prefix: string
+  private readonly ttlSeconds: number
+  private readonly memory: MemoryContentCache
+
+  constructor (kv: KVNamespace, options?: { prefix?: string, ttlSeconds?: number }) {
+    this.kv = kv
+    this.prefix = options?.prefix ?? 'content:'
+    this.ttlSeconds = options?.ttlSeconds ?? DEFAULT_KV_TTL_SECONDS
+    // In-memory layer for hot-path within the same isolate
+    this.memory = new MemoryContentCache(this.ttlSeconds * 1000)
+  }
+
+  async getPage (key: string): Promise<ContentPage | null> {
+    // L1: in-memory
+    const memResult = await this.memory.getPage(key)
+    if (memResult != null) return memResult
+
+    // L2: KV
+    const raw = await this.kv.get(this.prefix + 'page:' + key)
+    if (raw != null) {
+      try {
+        const page = JSON.parse(raw) as ContentPage
+        await this.memory.setPage(key, page)
+        return page
+      } catch {
+        return null
+      }
+    }
+    return null
+  }
+
+  async setPage (key: string, page: ContentPage): Promise<void> {
+    await this.memory.setPage(key, page)
+    await this.kv.put(this.prefix + 'page:' + key, JSON.stringify(page), {
+      expirationTtl: this.ttlSeconds
+    })
+  }
+
+  async getNav (): Promise<NavNode | null> {
+    const memResult = await this.memory.getNav()
+    if (memResult != null) return memResult
+
+    const raw = await this.kv.get(this.prefix + 'nav')
+    if (raw != null) {
+      try {
+        const nav = JSON.parse(raw) as NavNode
+        await this.memory.setNav(nav)
+        return nav
+      } catch {
+        return null
+      }
+    }
+    return null
+  }
+
+  async setNav (nav: NavNode): Promise<void> {
+    await this.memory.setNav(nav)
+    await this.kv.put(this.prefix + 'nav', JSON.stringify(nav), {
+      expirationTtl: this.ttlSeconds
+    })
+  }
+
+  async getPageList (): Promise<ContentPage[] | null> {
+    const memResult = await this.memory.getPageList()
+    if (memResult != null) return memResult
+
+    const raw = await this.kv.get(this.prefix + 'pages')
+    if (raw != null) {
+      try {
+        const pages = JSON.parse(raw) as ContentPage[]
+        await this.memory.setPageList(pages)
+        return pages
+      } catch {
+        return null
+      }
+    }
+    return null
+  }
+
+  async setPageList (pages: ContentPage[]): Promise<void> {
+    await this.memory.setPageList(pages)
+    await this.kv.put(this.prefix + 'pages', JSON.stringify(pages), {
+      expirationTtl: this.ttlSeconds
+    })
+  }
+
+  async getSearchIndex (): Promise<string | null> {
+    // L1: in-memory
+    const memResult = await this.memory.getSearchIndex()
+    if (memResult != null) return memResult
+
+    // L2: KV (search index stored as raw string, already JSON)
+    const raw = await this.kv.get(this.prefix + 'search-index')
+    if (raw != null) {
+      await this.memory.setSearchIndex(raw)
+      return raw
+    }
+    return null
+  }
+
+  async setSearchIndex (data: string): Promise<void> {
+    await this.memory.setSearchIndex(data)
+    await this.kv.put(this.prefix + 'search-index', data, {
+      expirationTtl: this.ttlSeconds
+    })
+  }
+
+  async clear (): Promise<void> {
+    await this.memory.clear()
+    // List and delete all keys with our prefix
+    try {
+      const result = await this.kv.list({ prefix: this.prefix })
+      await Promise.all(result.keys.map(async k => await this.kv.delete(k.name)))
+    } catch {
+      // Best-effort cleanup — KV TTL will handle expiry
+    }
+  }
+}