mkdnsite 0.0.1

package/src/cli.ts

@@ -0,0 +1,140 @@
+#!/usr/bin/env bun
+import { resolve } from 'node:path'
+import { access } from 'node:fs/promises'
+import { resolveConfig } from './config/defaults.ts'
+import type { MkdnSiteConfig } from './config/schema.ts'
+import { LocalAdapter } from './adapters/local.ts'
+import { createHandler } from './handler.ts'
+
+function parseArgs (args: string[]): Partial<MkdnSiteConfig> {
+  const result: Record<string, unknown> = {}
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+
+    if (arg === '--port' || arg === '-p') {
+      result.server = { ...(result.server as object ?? {}), port: parseInt(args[++i], 10) }
+    } else if (arg === '--title') {
+      result.site = { ...(result.site as object ?? {}), title: args[++i] }
+    } else if (arg === '--url') {
+      result.site = { ...(result.site as object ?? {}), url: args[++i] }
+    } else if (arg === '--no-nav') {
+      result.theme = { ...(result.theme as object ?? {}), showNav: false }
+    } else if (arg === '--no-llms-txt') {
+      result.llmsTxt = { enabled: false }
+    } else if (arg === '--no-negotiate') {
+      result.negotiation = { enabled: false }
+    } else if (arg === '--no-client-js') {
+      result.client = { enabled: false, mermaid: false, copyButton: false, themeToggle: false, math: false, search: false }
+    } else if (arg === '--no-theme-toggle') {
+      result.client = { ...(result.client as object ?? {}), themeToggle: false }
+    } else if (arg === '--no-math') {
+      result.client = { ...(result.client as object ?? {}), math: false }
+    } else if (arg === '--color-scheme') {
+      result.theme = { ...(result.theme as object ?? {}), colorScheme: args[++i] }
+    } else if (arg === '--theme-mode') {
+      result.theme = { ...(result.theme as object ?? {}), mode: args[++i] }
+    } else if (arg === '--renderer') {
+      result.renderer = args[++i]
+    } else if (arg === '--static') {
+      result.staticDir = resolve(args[++i])
+    } else if (arg === '--help' || arg === '-h') {
+      printHelp()
+      process.exit(0)
+    } else if (arg === '--version' || arg === '-v') {
+      console.log('mkdnsite 0.0.1')
+      process.exit(0)
+    } else if (!arg.startsWith('-')) {
+      result.contentDir = resolve(arg)
+    }
+  }
+
+  return result as Partial<MkdnSiteConfig>
+}
+
+function printHelp (): void {
+  console.log(`
+  mkdnsite — Markdown for the web
+
+  Usage:
+    mkdnsite [directory] [options]
+
+  Arguments:
+    directory             Path to markdown content (default: ./content)
+
+  Options:
+    -p, --port <n>        Port to listen on (default: 3000)
+    --title <text>        Site title
+    --url <url>           Base URL for absolute links
+    --static <dir>        Directory for static assets
+    --color-scheme <val>  Color scheme: system (default), light, or dark
+    --theme-mode <mode>   Theme mode: prose (default) or components
+    --no-nav              Disable navigation sidebar
+    --no-llms-txt         Disable /llms.txt generation
+    --no-negotiate        Disable content negotiation
+    --renderer <engine>   Renderer: portable (default) or bun-native (Bun only)
+    --no-client-js        Disable client-side JavaScript (mermaid, copy, search, theme toggle)
+    --no-theme-toggle     Disable light/dark theme toggle button
+    --no-math             Disable KaTeX math rendering
+    -h, --help            Show this help
+    -v, --version         Show version
+
+  Content Negotiation:
+    Browsers get HTML:    curl http://localhost:3000
+    AI agents get MD:     curl -H "Accept: text/markdown" http://localhost:3000
+    Append .md to URL:    curl http://localhost:3000/page.md
+    AI content index:     curl http://localhost:3000/llms.txt
+
+  https://mkdn.site
+  `)
+}
+
+async function main (): Promise<void> {
+  const args = process.argv.slice(2)
+  const cliConfig = parseArgs(args)
+
+  // Try to load mkdnsite.config.ts from cwd
+  let fileConfig: Partial<MkdnSiteConfig> = {}
+  try {
+    const configPath = resolve('mkdnsite.config.ts')
+    await access(configPath)
+    const mod = await import(configPath)
+    fileConfig = mod.default ?? mod
+  } catch {
+    // No config file, that's fine
+  }
+
+  const merged: Partial<MkdnSiteConfig> = {
+    ...fileConfig,
+    ...cliConfig
+  }
+  if (fileConfig.site != null || cliConfig.site != null) {
+    const site: Partial<MkdnSiteConfig['site']> = { ...fileConfig.site, ...cliConfig.site }
+    merged.site = site as MkdnSiteConfig['site']
+  }
+  if (fileConfig.server != null || cliConfig.server != null) {
+    const server: Partial<MkdnSiteConfig['server']> = { ...fileConfig.server, ...cliConfig.server }
+    merged.server = server as MkdnSiteConfig['server']
+  }
+  if (fileConfig.theme != null || cliConfig.theme != null) {
+    const theme: Partial<MkdnSiteConfig['theme']> = { ...fileConfig.theme, ...cliConfig.theme }
+    merged.theme = theme as MkdnSiteConfig['theme']
+  }
+  if (fileConfig.client != null || cliConfig.client != null) {
+    const client: Partial<MkdnSiteConfig['client']> = { ...fileConfig.client, ...cliConfig.client }
+    merged.client = client as MkdnSiteConfig['client']
+  }
+  const config = resolveConfig(merged)
+
+  const adapter = new LocalAdapter()
+  const source = adapter.createContentSource(config)
+  const renderer = await adapter.createRenderer(config)
+  const handler = createHandler({ source, renderer, config })
+
+  await adapter.start(handler, config)
+}
+
+main().catch(err => {
+  console.error('Error starting mkdnsite:', err)
+  process.exit(1)
+})

package/src/client/scripts.ts

@@ -0,0 +1,106 @@
+import type { ClientConfig } from '../config/schema.ts'
+
+/**
+ * Generate client-side JavaScript for progressive enhancements.
+ * Returns a <script> tag string or empty string if all features are disabled.
+ */
+export function CLIENT_SCRIPTS (client: ClientConfig): string {
+  if (!client.enabled) return ''
+
+  const scripts: string[] = []
+
+  if (client.themeToggle) {
+    scripts.push(THEME_TOGGLE_SCRIPT)
+  }
+
+  if (client.copyButton) {
+    scripts.push(COPY_BUTTON_SCRIPT)
+  }
+
+  if (client.mermaid) {
+    scripts.push(MERMAID_SCRIPT)
+  }
+
+  if (client.search) {
+    scripts.push(SEARCH_SCRIPT)
+  }
+
+  if (scripts.length === 0) return ''
+
+  return `<script>${scripts.join('\n')}</script>`
+}
+
+const THEME_TOGGLE_SCRIPT = `
+(function(){
+  var btn = document.querySelector('.mkdn-theme-toggle');
+  if (!btn) return;
+  btn.addEventListener('click', function(e){
+    var isDark = document.documentElement.getAttribute('data-theme') === 'dark';
+    var next = isDark ? 'light' : 'dark';
+    var rect = btn.getBoundingClientRect();
+    var x = rect.left + rect.width / 2;
+    var y = rect.top + rect.height / 2;
+    document.documentElement.style.setProperty('--mkdn-toggle-x', x + 'px');
+    document.documentElement.style.setProperty('--mkdn-toggle-y', y + 'px');
+    function apply(){
+      document.documentElement.setAttribute('data-theme', next);
+      localStorage.setItem('mkdn-theme', next);
+    }
+    if (document.startViewTransition) {
+      document.startViewTransition(apply);
+    } else {
+      apply();
+    }
+  });
+})();
+`.trim()
+
+const COPY_BUTTON_SCRIPT = `
+(function(){
+  document.querySelectorAll('.mkdn-code-block, .mkdn-prose pre').forEach(function(block){
+    var code = block.querySelector('code');
+    if(!code) return;
+    if(code.classList.contains('language-mermaid')) return;
+    var btn = document.createElement('button');
+    btn.className = 'mkdn-copy-btn';
+    btn.textContent = 'Copy';
+    btn.addEventListener('click', function(){
+      navigator.clipboard.writeText(code.textContent||'').then(function(){
+        btn.textContent = 'Copied!';
+        setTimeout(function(){ btn.textContent = 'Copy'; }, 2000);
+      });
+    });
+    block.style.position = 'relative';
+    block.appendChild(btn);
+  });
+})();
+`.trim()
+
+const MERMAID_SCRIPT = `
+(function(){
+  var mermaidBlocks = document.querySelectorAll('code.language-mermaid');
+  if(mermaidBlocks.length === 0) return;
+  var s = document.createElement('script');
+  s.src = 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js';
+  s.onload = function(){
+    mermaid.initialize({ startOnLoad: false, theme: 'default' });
+    mermaidBlocks.forEach(function(block){
+      var pre = block.parentElement;
+      var container = document.createElement('div');
+      container.className = 'mkdn-mermaid';
+      var id = 'mermaid-' + Math.random().toString(36).substr(2, 9);
+      mermaid.render(id, block.textContent||'').then(function(result){
+        container.innerHTML = result.svg;
+        pre.parentElement.replaceChild(container, pre);
+      });
+    });
+  };
+  document.head.appendChild(s);
+})();
+`.trim()
+
+const SEARCH_SCRIPT = `
+/* Search: placeholder for client-side search functionality.
+   Will be implemented with a pre-built content index served at /search-index.json.
+   For MVP, this is a no-op that can be activated once the index endpoint exists. */
+`.trim()

package/src/config/defaults.ts

@@ -0,0 +1,68 @@
+import type { MkdnSiteConfig } from './schema.ts'
+
+export const DEFAULT_CONFIG: MkdnSiteConfig = {
+  contentDir: './content',
+  site: {
+    title: 'mkdnsite',
+    lang: 'en'
+  },
+  server: {
+    port: 3000,
+    hostname: '0.0.0.0'
+  },
+  theme: {
+    mode: 'prose',
+    showNav: true,
+    showToc: true,
+    colorScheme: 'system',
+    syntaxTheme: 'github-light',
+    syntaxThemeDark: 'github-dark'
+  },
+  negotiation: {
+    enabled: true,
+    includeTokenCount: true,
+    contentSignals: {
+      aiTrain: 'yes',
+      search: 'yes',
+      aiInput: 'yes'
+    }
+  },
+  llmsTxt: {
+    enabled: true
+  },
+  client: {
+    enabled: true,
+    mermaid: true,
+    copyButton: true,
+    themeToggle: true,
+    math: true,
+    search: true
+  },
+  renderer: 'portable'
+}
+
+/**
+ * Deep merge user config with defaults.
+ * User values take precedence at every nesting level.
+ */
+export function resolveConfig (
+  userConfig: Partial<MkdnSiteConfig>
+): MkdnSiteConfig {
+  return {
+    ...DEFAULT_CONFIG,
+    ...userConfig,
+    site: { ...DEFAULT_CONFIG.site, ...userConfig.site },
+    server: { ...DEFAULT_CONFIG.server, ...userConfig.server },
+    theme: { ...DEFAULT_CONFIG.theme, ...userConfig.theme },
+    negotiation: {
+      ...DEFAULT_CONFIG.negotiation,
+      ...userConfig.negotiation,
+      contentSignals: {
+        ...DEFAULT_CONFIG.negotiation.contentSignals,
+        ...userConfig.negotiation?.contentSignals
+      }
+    },
+    llmsTxt: { ...DEFAULT_CONFIG.llmsTxt, ...userConfig.llmsTxt },
+    client: { ...DEFAULT_CONFIG.client, ...userConfig.client }
+  }
+}

package/src/config/schema.ts

@@ -0,0 +1,192 @@
+import type { ComponentType, ReactNode } from 'react'
+
+/**
+ * Top-level mkdnsite configuration.
+ *
+ * Can be defined in mkdnsite.config.ts at the project root,
+ * or passed programmatically when creating a handler.
+ */
+export interface MkdnSiteConfig {
+  /** Directory containing .md files (default: ./content) */
+  contentDir: string
+
+  /** Site metadata */
+  site: SiteConfig
+
+  /** Server options (local dev / self-hosted only) */
+  server: ServerConfig
+
+  /** Theme and rendering configuration */
+  theme: ThemeConfig
+
+  /** Content negotiation options */
+  negotiation: NegotiationConfig
+
+  /** Auto-generate /llms.txt */
+  llmsTxt: LlmsTxtConfig
+
+  /** Client-side enhancement modules */
+  client: ClientConfig
+
+  /** Markdown renderer engine (default: 'portable') */
+  renderer: RendererEngine
+
+  /** Static files directory for images, videos, etc. */
+  staticDir?: string
+}
+
+export interface SiteConfig {
+  title: string
+  description?: string
+  url?: string
+  lang?: string
+}
+
+export interface ServerConfig {
+  port: number
+  hostname: string
+}
+
+export interface ThemeConfig {
+  /**
+   * Rendering mode for markdown content.
+   * - 'prose': Uses @tailwindcss/typography prose classes (default)
+   * - 'components': Full custom React component overrides per element
+   */
+  mode: 'prose' | 'components'
+
+  /** Custom React components to override default element rendering */
+  components?: ComponentOverrides
+
+  /** Custom CSS file path or URL to use instead of default theme */
+  customCss?: string
+
+  /** Show navigation sidebar */
+  showNav: boolean
+
+  /** Show table of contents per page */
+  showToc: boolean
+
+  /** Edit URL template (e.g. https://github.com/org/repo/edit/main/{path}) */
+  editUrl?: string
+
+  /** Color scheme: 'system' (default), 'light', or 'dark' */
+  colorScheme: 'system' | 'light' | 'dark'
+
+  /** Syntax highlighting theme for Shiki */
+  syntaxTheme: string
+
+  /** Dark mode syntax highlighting theme */
+  syntaxThemeDark?: string
+}
+
+export interface NegotiationConfig {
+  /** Enable serving raw markdown via Accept: text/markdown (default: true) */
+  enabled: boolean
+
+  /** Include x-markdown-tokens header (default: true) */
+  includeTokenCount: boolean
+
+  /** Content-Signal header values */
+  contentSignals: ContentSignals
+}
+
+export interface ContentSignals {
+  aiTrain: 'yes' | 'no'
+  search: 'yes' | 'no'
+  aiInput: 'yes' | 'no'
+}
+
+export interface LlmsTxtConfig {
+  enabled: boolean
+  description?: string
+  sections?: Record<string, string>
+}
+
+export interface ClientConfig {
+  /**
+   * Enable client-side JavaScript enhancements.
+   * When false, only static HTML/CSS is served (performance mode).
+   * Default: true
+   */
+  enabled: boolean
+
+  /** Enable Mermaid diagram rendering (default: true when client enabled) */
+  mermaid: boolean
+
+  /** Enable copy-to-clipboard on code blocks (default: true when client enabled) */
+  copyButton: boolean
+
+  /** Enable light/dark theme toggle button (default: true when client enabled) */
+  themeToggle: boolean
+
+  /** Enable KaTeX math rendering (default: true when client enabled) */
+  math: boolean
+
+  /** Enable client-side search (default: true when client enabled) */
+  search: boolean
+}
+
+/**
+ * Markdown renderer engine selection.
+ * - 'portable': react-markdown + remark/rehype (works everywhere)
+ * - 'bun-native': Bun.markdown.react() (Bun only, faster)
+ */
+export type RendererEngine = 'portable' | 'bun-native'
+
+/**
+ * React component overrides for markdown elements.
+ * Each key maps to an HTML element produced by the markdown renderer.
+ */
+export interface ComponentOverrides {
+  h1?: ComponentType<HeadingProps>
+  h2?: ComponentType<HeadingProps>
+  h3?: ComponentType<HeadingProps>
+  h4?: ComponentType<HeadingProps>
+  h5?: ComponentType<HeadingProps>
+  h6?: ComponentType<HeadingProps>
+  p?: ComponentType<{ children?: ReactNode }>
+  a?: ComponentType<LinkProps>
+  img?: ComponentType<ImageProps>
+  pre?: ComponentType<CodeBlockProps>
+  code?: ComponentType<InlineCodeProps>
+  blockquote?: ComponentType<{ children?: ReactNode }>
+  table?: ComponentType<{ children?: ReactNode }>
+  thead?: ComponentType<{ children?: ReactNode }>
+  tbody?: ComponentType<{ children?: ReactNode }>
+  tr?: ComponentType<{ children?: ReactNode }>
+  th?: ComponentType<{ children?: ReactNode, align?: string }>
+  td?: ComponentType<{ children?: ReactNode, align?: string }>
+  ul?: ComponentType<{ children?: ReactNode }>
+  ol?: ComponentType<{ children?: ReactNode, start?: number }>
+  li?: ComponentType<{ children?: ReactNode, checked?: boolean }>
+  hr?: ComponentType<Record<string, never>>
+}
+
+export interface HeadingProps {
+  children?: ReactNode
+  id?: string
+  level: number
+}
+
+export interface LinkProps {
+  children?: ReactNode
+  href?: string
+  title?: string
+}
+
+export interface ImageProps {
+  src?: string
+  alt?: string
+  title?: string
+}
+
+export interface CodeBlockProps {
+  children?: ReactNode
+  language?: string
+  raw?: string
+}
+
+export interface InlineCodeProps {
+  children?: ReactNode
+}