mkdnsite 0.0.1

package/src/handler.ts

@@ -0,0 +1,188 @@
+import { readFile } from 'node:fs/promises'
+import { extname } from 'node:path'
+import type { MkdnSiteConfig } from './config/schema.ts'
+import type { ContentSource } from './content/types.ts'
+import type { MarkdownRenderer } from './render/types.ts'
+import { negotiateFormat } from './negotiate/accept.ts'
+import { markdownHeaders, htmlHeaders, estimateTokens } from './negotiate/headers.ts'
+import { renderPage, render404 } from './render/page-shell.ts'
+import { generateLlmsTxt } from './discovery/llmstxt.ts'
+
+export interface HandlerOptions {
+  source: ContentSource
+  renderer: MarkdownRenderer
+  config: MkdnSiteConfig
+}
+
+/**
+ * Create a portable fetch handler for mkdnsite.
+ *
+ * This handler conforms to the Web API fetch(request): Response
+ * pattern, making it compatible with:
+ * - Bun.serve()
+ * - Cloudflare Workers
+ * - Vercel Edge Functions
+ * - Netlify Edge Functions
+ * - Deno.serve()
+ */
+export function createHandler (opts: HandlerOptions): (request: Request) => Promise<Response> {
+  const { source, renderer, config } = opts
+
+  let llmsTxtCache: string | null = null
+
+  return async function handler (request: Request): Promise<Response> {
+    const url = new URL(request.url)
+    const pathname = decodeURIComponent(url.pathname)
+
+    // ---- Special routes ----
+
+    if (pathname === '/_health') {
+      return new Response('ok', { status: 200 })
+    }
+
+    if (pathname === '/llms.txt' && config.llmsTxt.enabled) {
+      if (llmsTxtCache == null) {
+        llmsTxtCache = await generateLlmsTxt(source, config)
+      }
+      return new Response(llmsTxtCache, {
+        status: 200,
+        headers: {
+          'Content-Type': 'text/markdown; charset=utf-8',
+          'Cache-Control': 'public, max-age=3600'
+        }
+      })
+    }
+
+    if (pathname === '/_refresh' && request.method === 'POST') {
+      await source.refresh()
+      llmsTxtCache = null
+      return new Response('cache cleared', { status: 200 })
+    }
+
+    // ---- Static files passthrough ----
+    if (config.staticDir != null && hasStaticExtension(pathname)) {
+      return await serveStatic(pathname, config.staticDir)
+    }
+
+    // ---- Content negotiation + page serving ----
+
+    let slug = pathname
+    let forceMarkdown = false
+
+    if (slug.endsWith('.md')) {
+      slug = slug.slice(0, -3)
+      forceMarkdown = true
+    }
+
+    if (slug !== '/' && slug.endsWith('/')) {
+      slug = slug.slice(0, -1)
+    }
+
+    const page = await source.getPage(slug)
+
+    if (page == null) {
+      const format = negotiateFormat(request.headers.get('Accept'))
+      if (format === 'markdown') {
+        return new Response(
+          '# 404 — Page Not Found\n\nThe requested page does not exist.\n',
+          {
+            status: 404,
+            headers: { 'Content-Type': 'text/markdown; charset=utf-8' }
+          }
+        )
+      }
+      return new Response(render404(config), {
+        status: 404,
+        headers: htmlHeaders()
+      })
+    }
+
+    const format = forceMarkdown
+      ? 'markdown'
+      : negotiateFormat(request.headers.get('Accept'))
+
+    if (format === 'markdown') {
+      const tokens = config.negotiation.includeTokenCount
+        ? estimateTokens(page.body)
+        : null
+
+      return new Response(page.body, {
+        status: 200,
+        headers: markdownHeaders(tokens, config.negotiation.contentSignals)
+      })
+    }
+
+    // ---- Render HTML via React SSR ----
+    const renderedHtml = renderer.renderToHtml(page.body, config.theme.components)
+    const nav = config.theme.showNav
+      ? await source.getNavTree()
+      : undefined
+
+    const fullPage = renderPage({
+      renderedContent: renderedHtml,
+      meta: page.meta,
+      config,
+      nav,
+      currentSlug: page.slug
+    })
+
+    return new Response(fullPage, {
+      status: 200,
+      headers: htmlHeaders()
+    })
+  }
+}
+
+const STATIC_EXTENSIONS = new Set([
+  '.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg', '.ico',
+  '.mp4', '.webm', '.ogg', '.mp3', '.wav',
+  '.pdf', '.zip', '.tar', '.gz',
+  '.css', '.js', '.json', '.xml',
+  '.woff', '.woff2', '.ttf', '.eot'
+])
+
+function hasStaticExtension (pathname: string): boolean {
+  const ext = pathname.slice(pathname.lastIndexOf('.')).toLowerCase()
+  return STATIC_EXTENSIONS.has(ext)
+}
+
+const MIME_TYPES: Record<string, string> = {
+  '.html': 'text/html',
+  '.css': 'text/css',
+  '.js': 'application/javascript',
+  '.json': 'application/json',
+  '.xml': 'application/xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.svg': 'image/svg+xml',
+  '.ico': 'image/x-icon',
+  '.mp4': 'video/mp4',
+  '.webm': 'video/webm',
+  '.ogg': 'audio/ogg',
+  '.mp3': 'audio/mpeg',
+  '.wav': 'audio/wav',
+  '.pdf': 'application/pdf',
+  '.zip': 'application/zip',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.eot': 'application/vnd.ms-fontobject'
+}
+
+async function serveStatic (pathname: string, staticDir: string): Promise<Response> {
+  try {
+    const filePath = `${staticDir}${pathname}`
+    const data = await readFile(filePath)
+    const ext = extname(pathname).toLowerCase()
+    const contentType = MIME_TYPES[ext] ?? 'application/octet-stream'
+    return new Response(data, {
+      status: 200,
+      headers: { 'Content-Type': contentType }
+    })
+  } catch {
+    return new Response('Not Found', { status: 404 })
+  }
+}

package/src/index.ts

@@ -0,0 +1,57 @@
+/**
+ * mkdnsite — Markdown for the web.
+ * HTML for humans, Markdown for agents.
+ *
+ * @module mkdnsite
+ */
+
+// Core handler
+export { createHandler } from './handler.ts'
+export type { HandlerOptions } from './handler.ts'
+
+// Config
+export { resolveConfig, DEFAULT_CONFIG } from './config/defaults.ts'
+export type {
+  MkdnSiteConfig,
+  ThemeConfig,
+  NegotiationConfig,
+  ClientConfig,
+  ComponentOverrides,
+  RendererEngine,
+  HeadingProps,
+  LinkProps,
+  ImageProps,
+  CodeBlockProps,
+  InlineCodeProps
+} from './config/schema.ts'
+
+// Content sources
+export { FilesystemSource } from './content/filesystem.ts'
+export { GitHubSource } from './content/github.ts'
+export type {
+  ContentSource,
+  ContentPage,
+  NavNode,
+  MarkdownMeta,
+  GitHubSourceConfig
+} from './content/types.ts'
+export { parseFrontmatter } from './content/frontmatter.ts'
+
+// Rendering
+export { createRenderer } from './render/types.ts'
+export type { MarkdownRenderer } from './render/types.ts'
+export { PortableRenderer } from './render/portable.ts'
+export { buildComponents } from './render/components/index.ts'
+
+// Content negotiation
+export { negotiateFormat } from './negotiate/accept.ts'
+export type { ResponseFormat } from './negotiate/accept.ts'
+export { markdownHeaders, htmlHeaders, estimateTokens } from './negotiate/headers.ts'
+
+// Discovery
+export { generateLlmsTxt } from './discovery/llmstxt.ts'
+
+// Adapters
+export type { DeploymentAdapter } from './adapters/types.ts'
+export { detectRuntime } from './adapters/types.ts'
+export { LocalAdapter } from './adapters/local.ts'

package/src/negotiate/accept.ts

@@ -0,0 +1,72 @@
+export type ResponseFormat = 'html' | 'markdown'
+
+/**
+ * Parse the Accept header and determine the preferred response format.
+ */
+export function negotiateFormat (acceptHeader: string | null): ResponseFormat {
+  if (acceptHeader == null) return 'html'
+
+  const types = parseAcceptHeader(acceptHeader)
+
+  let markdownQ = -1
+  let htmlQ = -1
+
+  for (const { type, quality } of types) {
+    if (
+      type === 'text/markdown' ||
+      type === 'text/x-markdown' ||
+      type === 'application/markdown'
+    ) {
+      markdownQ = Math.max(markdownQ, quality)
+    } else if (type === 'text/html') {
+      htmlQ = Math.max(htmlQ, quality)
+    } else if (type === '*/*') {
+      if (htmlQ < 0) htmlQ = quality * 0.01
+    }
+  }
+
+  if (markdownQ > htmlQ && markdownQ > 0) {
+    return 'markdown'
+  }
+
+  if (markdownQ === htmlQ && markdownQ > 0) {
+    const markdownIdx = types.findIndex(t =>
+      t.type === 'text/markdown' ||
+      t.type === 'text/x-markdown' ||
+      t.type === 'application/markdown'
+    )
+    const htmlIdx = types.findIndex(t => t.type === 'text/html')
+
+    if (markdownIdx >= 0 && (htmlIdx < 0 || markdownIdx < htmlIdx)) {
+      return 'markdown'
+    }
+  }
+
+  return 'html'
+}
+
+interface ParsedMediaType {
+  type: string
+  quality: number
+}
+
+function parseAcceptHeader (header: string): ParsedMediaType[] {
+  return header
+    .split(',')
+    .map(part => {
+      const trimmed = part.trim()
+      const [type, ...params] = trimmed.split(';').map(s => s.trim())
+
+      let quality = 1.0
+      for (const param of params) {
+        const match = param.match(/^q=([\d.]+)$/)
+        if (match != null) {
+          quality = parseFloat(match[1])
+          break
+        }
+      }
+
+      return { type: type.toLowerCase(), quality }
+    })
+    .sort((a, b) => b.quality - a.quality)
+}

package/src/negotiate/headers.ts

@@ -0,0 +1,56 @@
+import type { ContentSignals } from '../config/schema.ts'
+
+export function markdownHeaders (
+  tokenCount: number | null,
+  signals?: ContentSignals
+): Record<string, string> {
+  const headers: Record<string, string> = {
+    'Content-Type': 'text/markdown; charset=utf-8',
+    Vary: 'Accept',
+    'Cache-Control': 'public, max-age=300'
+  }
+
+  if (tokenCount != null) {
+    headers['x-markdown-tokens'] = String(tokenCount)
+  }
+
+  if (signals != null) {
+    const parts: string[] = []
+    if (signals.aiTrain !== undefined) parts.push(`ai-train=${signals.aiTrain}`)
+    if (signals.search !== undefined) parts.push(`search=${signals.search}`)
+    if (signals.aiInput !== undefined) parts.push(`ai-input=${signals.aiInput}`)
+    if (parts.length > 0) {
+      headers['Content-Signal'] = parts.join(', ')
+    }
+  }
+
+  return headers
+}
+
+export function htmlHeaders (): Record<string, string> {
+  return {
+    'Content-Type': 'text/html; charset=utf-8',
+    Vary: 'Accept',
+    'Cache-Control': 'public, max-age=300'
+  }
+}
+
+/**
+ * Rough token count estimation for x-markdown-tokens header.
+ * Approximation (~4 chars per token for English text).
+ */
+export function estimateTokens (text: string): number {
+  if (text === '') return 0
+
+  const words = text.split(/\s+/).filter(Boolean)
+  let tokens = 0
+
+  for (const word of words) {
+    tokens += word.length <= 4 ? 1 : Math.ceil(word.length / 3.5)
+  }
+
+  const syntaxOverhead = (text.match(/[#*_`[\](){}|>~-]{2,}/g) ?? []).length
+  tokens += syntaxOverhead
+
+  return Math.max(1, Math.round(tokens))
+}

package/src/render/bun-native.ts

@@ -0,0 +1,54 @@
+import { renderToString } from 'react-dom/server'
+import type { ReactElement } from 'react'
+import type { ComponentOverrides } from '../config/schema.ts'
+import type { MarkdownRenderer } from './types.ts'
+import { buildComponents } from './components/index.ts'
+
+/**
+ * High-performance renderer using Bun.markdown.react().
+ *
+ * Only works in Bun runtime. Uses Bun's built-in Zig-based
+ * markdown parser which is significantly faster than JavaScript
+ * alternatives.
+ *
+ * Falls back gracefully if Bun.markdown is not available.
+ */
+export class BunNativeRenderer implements MarkdownRenderer {
+  readonly engine = 'bun-native' as const
+
+  renderToElement (markdown: string, overrides?: ComponentOverrides): ReactElement {
+    const components = buildComponents(overrides)
+
+    // Map our ComponentOverrides to Bun.markdown.react() component shape
+    // Bun.markdown.react() accepts overrides keyed by HTML tag name
+    const bunComponents: Record<string, unknown> = {}
+
+    if (components.h1 != null) bunComponents.h1 = components.h1
+    if (components.h2 != null) bunComponents.h2 = components.h2
+    if (components.h3 != null) bunComponents.h3 = components.h3
+    if (components.h4 != null) bunComponents.h4 = components.h4
+    if (components.h5 != null) bunComponents.h5 = components.h5
+    if (components.h6 != null) bunComponents.h6 = components.h6
+    if (components.a != null) bunComponents.a = components.a
+    if (components.img != null) bunComponents.img = components.img
+    if (components.pre != null) bunComponents.pre = components.pre
+    if (components.code != null) bunComponents.code = components.code
+    if (components.blockquote != null) bunComponents.blockquote = components.blockquote
+    if (components.table != null) bunComponents.table = components.table
+    if (components.p != null) bunComponents.p = components.p
+
+    return Bun.markdown.react(markdown, bunComponents, {
+      tables: true,
+      strikethrough: true,
+      tasklists: true,
+      autolinks: true,
+      headings: { ids: true },
+      tagFilter: true
+    })
+  }
+
+  renderToHtml (markdown: string, overrides?: ComponentOverrides): string {
+    const element = this.renderToElement(markdown, overrides)
+    return renderToString(element)
+  }
+}

package/src/render/components/index.ts

@@ -0,0 +1,149 @@
+import React from 'react'
+import { Link as LinkIcon } from 'lucide-react'
+import type {
+  HeadingProps,
+  LinkProps,
+  ImageProps,
+  CodeBlockProps,
+  InlineCodeProps,
+  ComponentOverrides
+} from '../../config/schema.ts'
+
+const ICON_SIZES: Record<number, number> = {
+  1: 20,
+  2: 18,
+  3: 16
+}
+
+/**
+ * Default heading component with anchor link support.
+ * h1-h3 show a lucide link icon on hover; h4-h6 show a # symbol.
+ */
+function Heading ({ children, id, level }: HeadingProps): React.ReactElement {
+  const Tag = `h${level}` as 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'
+  const className = `mkdn-heading mkdn-h${level}`
+
+  if (id != null) {
+    const iconSize = ICON_SIZES[level]
+    const anchorChild = iconSize != null
+      ? React.createElement(LinkIcon, { size: iconSize, 'aria-hidden': true })
+      : '#'
+
+    return React.createElement(Tag, { id, className },
+      React.createElement('a', {
+        href: `#${id}`,
+        className: 'mkdn-heading-anchor',
+        'aria-hidden': 'true'
+      }, anchorChild),
+      ' ',
+      children
+    )
+  }
+
+  return React.createElement(Tag, { className }, children)
+}
+
+/**
+ * Default link component with external link detection.
+ */
+function Link ({ children, href, title }: LinkProps): React.ReactElement {
+  const isExternal = href?.startsWith('http://') === true || href?.startsWith('https://') === true
+  const props: Record<string, unknown> = {
+    href,
+    title,
+    className: 'mkdn-link'
+  }
+
+  if (isExternal) {
+    props.target = '_blank'
+    props.rel = 'noopener noreferrer'
+  }
+
+  return React.createElement('a', props, children)
+}
+
+/**
+ * Default image component with lazy loading.
+ */
+function Image ({ src, alt, title }: ImageProps): React.ReactElement {
+  return React.createElement('img', {
+    src,
+    alt: alt ?? '',
+    title,
+    loading: 'lazy',
+    className: 'mkdn-image'
+  })
+}
+
+/**
+ * Default code block component.
+ * Syntax highlighting is applied server-side by the renderer using Shiki.
+ * This component wraps the highlighted output.
+ */
+function CodeBlock ({ children, language }: CodeBlockProps): React.ReactElement {
+  return React.createElement('div', { className: 'mkdn-code-block', 'data-language': language },
+    React.createElement('pre', null,
+      React.createElement('code', {
+        className: language != null ? `language-${language}` : undefined
+      }, children)
+    )
+  )
+}
+
+/**
+ * Default inline code component.
+ */
+function InlineCode ({ children }: InlineCodeProps): React.ReactElement {
+  return React.createElement('code', { className: 'mkdn-inline-code' }, children)
+}
+
+/**
+ * Default blockquote component.
+ */
+function Blockquote ({ children }: { children?: React.ReactNode }): React.ReactElement {
+  return React.createElement('blockquote', { className: 'mkdn-blockquote' }, children)
+}
+
+/**
+ * Default table component with responsive wrapper.
+ */
+function Table ({ children }: { children?: React.ReactNode }): React.ReactElement {
+  return React.createElement('div', { className: 'mkdn-table-wrapper' },
+    React.createElement('table', { className: 'mkdn-table' }, children)
+  )
+}
+
+/**
+ * Build the full component overrides map, merging user overrides
+ * with defaults. User overrides take precedence.
+ */
+export function buildComponents (userOverrides?: ComponentOverrides): ComponentOverrides {
+  const defaults: ComponentOverrides = {
+    h1: (props) => Heading({ ...props, level: 1 }),
+    h2: (props) => Heading({ ...props, level: 2 }),
+    h3: (props) => Heading({ ...props, level: 3 }),
+    h4: (props) => Heading({ ...props, level: 4 }),
+    h5: (props) => Heading({ ...props, level: 5 }),
+    h6: (props) => Heading({ ...props, level: 6 }),
+    a: Link,
+    img: Image,
+    pre: CodeBlock,
+    code: InlineCode,
+    blockquote: Blockquote,
+    table: Table
+  }
+
+  if (userOverrides == null) return defaults
+
+  return { ...defaults, ...userOverrides }
+}
+
+export {
+  Heading,
+  Link,
+  Image,
+  CodeBlock,
+  InlineCode,
+  Blockquote,
+  Table
+}