@inglorious/ssx 1.3.6 → 1.4.1

package/README.md

@@ -32,6 +32,7 @@ SSX takes your entity-based web apps and generates optimized static HTML with fu
 - **lit-html hydration** - Interactive UI without the bloat
 - **TypeScript Ready** - Write your pages and entities in TypeScript.
 - **Image Optimization** - Automatic compression for static assets.
+- **Markdown Support** - Built-in support for `.md` pages with code highlighting and math.
 
 ### 🚀 Production Ready
 
@@ -397,6 +398,35 @@ SSX includes built-in image optimization using `vite-plugin-image-optimizer`.
 - **Automatic compression** - PNG, JPEG, GIF, SVG, WebP, and AVIF are compressed at build time.
 - **Lossless & Lossy** - Configurable settings via `vite` config in `site.config.js`.
 
+### 📝 Markdown Support
+
+SSX treats `.md` files as first-class pages. You can create `src/pages/post.md` and it will be rendered automatically.
+
+- **Frontmatter** - Metadata is exported as `metadata`.
+- **Code Highlighting** - Built-in syntax highlighting with `highlight.js`.
+- **Math Support** - LaTeX support via `katex` (use `$E=mc^2$` or `$$...$$`).
+- **Mermaid Diagrams** - Use `mermaid` code blocks (requires client-side mermaid.js).
+
+Configure the syntax highlighting theme in `site.config.js`:
+
+```javascript
+export default {
+  markdown: {
+    theme: "monokai", // default: "github-dark"
+  },
+}
+```
+
+```markdown
+---
+title: My Post
+---
+
+# Hello World
+
+This is a markdown page.
+```
+
 ---
 
 ## CLI
@@ -464,16 +494,15 @@ my-site/
 
 ## Comparison to Other Tools
 
-| Feature                 | SSX         | Next.js (SSG) | Astro  | Eleventy |
-| ----------------------- | ----------- | ------------- | ------ | -------- |
-| Pre-rendered HTML       | ✅          | ✅            | ✅     | ✅       |
-| Client hydration        | ✅ lit-html | ✅ React      | ✅ Any | ❌       |
-| Client routing          | ✅          | ✅            | ✅     | ❌       |
-| Lazy loading            | ✅          | ✅            | ✅     | ❌       |
-| Entity-based state      | ✅          | ❌            | ❌     | ❌       |
-| No compilation required | ✅          | ❌            | ❌     | ✅       |
-| Zero config             | ✅          | ❌            | ❌     | ❌       |
-| Framework agnostic      | ❌          | ❌            | ✅     | ✅       |
+| Feature            | SSX         | Next.js (SSG) | Astro  | Eleventy |
+| ------------------ | ----------- | ------------- | ------ | -------- |
+| Pre-rendered HTML  | ✅          | ✅            | ✅     | ✅       |
+| Client hydration   | ✅ lit-html | ✅ React      | ✅ Any | ❌       |
+| Client routing     | ✅          | ✅            | ✅     | ❌       |
+| Lazy loading       | ✅          | ✅            | ✅     | ❌       |
+| Entity-based state | ✅          | ❌            | ❌     | ❌       |
+| Zero config        | ✅          | ❌            | ❌     | ❌       |
+| Framework agnostic | ❌          | ❌            | ✅     | ✅       |
 
 SSX is perfect if you:
 
@@ -643,7 +672,7 @@ Check out these example projects:
 - [x] TypeScript support
 - [x] Image optimization
 - [ ] API routes (serverless functions)
-- [ ] MDX support
+- [x] Markdown support
 - [ ] i18n helpers
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/ssx",
-  "version": "1.3.6",
+  "version": "1.4.1",
   "description": "Server-Side-X. Xecution? Xperience? Who knows.",
   "author": "IceOnFire <antony.mistretta@gmail.com> (https://ingloriouscoderz.it)",
   "license": "MIT",
@@ -26,7 +26,8 @@
     "ssx": "./bin/ssx.js"
   },
   "exports": {
-    ".": "./types/index.d.ts"
+    ".": "./types/index.d.ts",
+    "./markdown": "./src/utils/markdown.js"
   },
   "files": [
     "bin",
@@ -44,12 +45,18 @@
     "connect": "^3.7.0",
     "fast-xml-parser": "^5.3.3",
     "glob": "^13.0.0",
+    "gray-matter": "^4.0.3",
+    "highlight.js": "^11.11.1",
+    "katex": "^0.16.27",
+    "markdown-it": "^14.1.0",
+    "markdown-it-texmath": "^1.0.0",
+    "mermaid": "^11.12.2",
     "rollup-plugin-minify-template-literals": "^1.1.7",
     "sharp": "^0.34.5",
     "svgo": "^4.0.0",
     "vite": "^7.1.3",
     "vite-plugin-image-optimizer": "^2.0.3",
-    "@inglorious/web": "4.0.2"
+    "@inglorious/web": "4.0.3"
   },
   "devDependencies": {
     "prettier": "^3.6.2",

package/src/build/index.js

@@ -103,10 +103,12 @@ export async function build(options = {}) {
     loader,
   )
   // For skipped pages, load their metadata from disk if needed for sitemap/RSS
-  const skippedPages = await generatePages(store, pagesToSkip, {
-    ...mergedOptions,
-    shouldGenerateHtml: false,
-  })
+  const skippedPages = await generatePages(
+    store,
+    pagesToSkip,
+    { ...mergedOptions, shouldGenerateHtml: false },
+    loader,
+  )
 
   // Combine rendered and skipped pages for sitemap/RSS
   const allGeneratedPages = [...changedPages, ...skippedPages]

package/src/build/metadata.js

@@ -24,9 +24,16 @@ export function extractPageMetadata(store, page, entity, options = {}) {
 
   // sitemap metadata
   const loc = `${hostname}${path}`
-  const lastmod = updatedAt
-    ? new Date(updatedAt).toISOString().split("T")[0]
-    : new Date().toISOString().split("T")[0]
+
+  let lastmod
+  try {
+    lastmod = updatedAt
+      ? new Date(updatedAt).toISOString().split("T")[0]
+      : new Date().toISOString().split("T")[0]
+  } catch {
+    console.warn(`⚠️  Invalid updatedAt date for page ${path}: ${updatedAt}`)
+    lastmod = new Date().toISOString().split("T")[0]
+  }
 
   // rss metadata
   const title = getPageOption("title", DEFAULT_OPTIONS)

package/src/build/metadata.test.js

@@ -0,0 +1,19 @@
+import { describe, expect, it, vi } from "vitest"
+
+import { extractPageMetadata } from "./metadata.js"
+
+describe("extractPageMetadata", () => {
+  it("should handle invalid updatedAt gracefully", () => {
+    const consoleSpy = vi.spyOn(console, "warn").mockImplementation(() => {})
+    const store = { _api: {} }
+    const page = {
+      path: "/test",
+      module: { metadata: { updatedAt: "invalid-date" } },
+    }
+    const entity = {}
+
+    const metadata = extractPageMetadata(store, page, entity)
+    expect(metadata.lastmod).toBeDefined()
+    expect(consoleSpy).toHaveBeenCalled()
+  })
+})

package/src/build/vite-config.js

@@ -3,6 +3,8 @@ import path from "node:path"
 import { mergeConfig } from "vite"
 import { ViteImageOptimizer } from "vite-plugin-image-optimizer"
 
+import { markdownPlugin } from "../utils/markdown.js"
+
 // import { minifyTemplateLiterals } from "rollup-plugin-minify-template-literals"
 
 /**
@@ -14,6 +16,7 @@ export function createViteConfig(options = {}) {
     outDir = "dist",
     publicDir = "public",
     vite = {},
+    markdown = {},
   } = options
 
   return mergeConfig(
@@ -25,6 +28,7 @@ export function createViteConfig(options = {}) {
         ViteImageOptimizer({
           // Options can be overridden by the user in site.config.js via the `vite` property
         }),
+        markdownPlugin(markdown),
       ],
       build: {
         outDir,

package/src/dev/vite-config.js

@@ -2,6 +2,8 @@ import path from "node:path"
 
 import { mergeConfig } from "vite"
 
+import { markdownPlugin } from "../utils/markdown.js"
+
 /**
  * Creates a Vite configuration object for the SSX dev server.
  * It sets up the root directory, public directory, aliases, and the virtual file plugin.
@@ -13,7 +15,12 @@ import { mergeConfig } from "vite"
  * @returns {Object} The merged Vite configuration.
  */
 export function createViteConfig(options = {}) {
-  const { rootDir = "src", publicDir = "public", vite = {} } = options
+  const {
+    rootDir = "src",
+    publicDir = "public",
+    vite = {},
+    markdown = {},
+  } = options
   const { port = 3000 } = vite.dev ?? {}
 
   return mergeConfig(
@@ -22,7 +29,7 @@ export function createViteConfig(options = {}) {
       publicDir: path.resolve(process.cwd(), rootDir, publicDir),
       server: { port, middlewareMode: true },
       appType: "custom",
-      plugins: [virtualPlugin()],
+      plugins: [virtualPlugin(), markdownPlugin(markdown)],
       resolve: {
         alias: {
           "@": path.resolve(process.cwd(), rootDir),

package/src/router/index.js

@@ -124,7 +124,7 @@ export async function resolvePage(url, pagesDir = "pages") {
  */
 export async function getRoutes(pagesDir = "pages") {
   // Find all .js and .ts files in pages directory
-  const files = await glob("**/*.{js,ts,jsx,tsx}", {
+  const files = await glob("**/*.{js,ts,jsx,tsx,md}", {
     cwd: pagesDir,
     ignore: ["**/*.test.{js,ts}", "**/*.spec.{js,ts}"],
     posix: true,
@@ -192,7 +192,7 @@ export function matchRoute(pattern, url) {
 function filePathToPattern(file) {
   let pattern = file
     .replace(/\\/g, "/")
-    .replace(/\.(js|ts|jsx|tsx)$/, "") // Remove extension
+    .replace(/\.(js|ts|jsx|tsx|md)$/, "") // Remove extension
     .replace(/\/index$/, "") // index becomes root of directory
     .replace(/^index$/, "") // Handle root index
     .replace(/__(\w+)/g, "*") // __path becomes *

package/src/router/router.test.js

@@ -39,7 +39,7 @@ describe("router", () => {
       // Root usually comes after specific paths but before catch-all if it was a catch-all root,
       // but here / is static.
       // Let's just check that we found them.
-      expect(routes).toHaveLength(5)
+      expect(routes).toHaveLength(6)
     })
   })
 
@@ -100,11 +100,11 @@ describe("router", () => {
       expect(pages).toMatchSnapshot()
 
       // Dynamic route without staticPaths should be skipped (and warn)
-      const blogPage = pages.find((p) => p.path.includes("/blog/"))
+      const blogPage = pages.find((p) => p.path.includes("/api/"))
       expect(blogPage).toBeUndefined()
 
       expect(consoleSpy).toHaveBeenCalled()
-      expect(consoleSpy.mock.calls[1][0]).toContain("has no staticPaths")
+      expect(consoleSpy.mock.calls[2][0]).toContain("has no staticPaths")
     })
   })
 

package/src/utils/markdown.js

@@ -0,0 +1,90 @@
+import hljs from "highlight.js"
+import katex from "katex"
+import MarkdownIt from "markdown-it"
+import texmath from "markdown-it-texmath"
+
+export function createMarkdownRenderer() {
+  const md = new MarkdownIt({
+    html: true,
+    linkify: true,
+    typographer: true,
+    highlight: (str, lang) => {
+      if (lang === "mermaid") {
+        return `<div class="mermaid">${str}</div>`
+      }
+      if (lang && hljs.getLanguage(lang)) {
+        try {
+          return hljs.highlight(str, { language: lang }).value
+        } catch (err) {
+          console.error(err)
+        }
+      }
+      return "" // use external default escaping
+    },
+  })
+
+  // Add LaTeX support
+  md.use(texmath, {
+    engine: katex,
+    delimiters: "dollars",
+    katexOptions: { macros: { "\\RR": "\\mathbb{R}" } },
+  })
+
+  return md
+}
+
+export function renderMarkdown(markdown) {
+  const md = createMarkdownRenderer()
+  // Simple frontmatter stripping for runtime rendering (avoids Buffer/gray-matter on client)
+  const content = markdown.replace(/^---[\s\S]*?---\n/, "")
+  return md.render(content)
+}
+
+export function markdownPlugin(options = {}) {
+  const { theme = "github-dark" } = options
+  const md = createMarkdownRenderer()
+
+  return {
+    name: "ssx-markdown",
+    enforce: "pre",
+    async transform(code, id) {
+      if (!id.endsWith(".md")) return
+
+      const matter = (await import("gray-matter")).default
+      const { content, data } = matter(code)
+      const htmlContent = md.render(content)
+      const hasMermaid =
+        content.includes('class="mermaid"') || content.includes("```mermaid")
+
+      let mermaidCode = ""
+      if (hasMermaid) {
+        mermaidCode = `
+          import mermaid from "mermaid"
+          if (typeof window !== "undefined") {
+            mermaid.initialize({ startOnLoad: false })
+          }
+        `
+      }
+
+      return `
+        import { html, unsafeHTML } from "@inglorious/web"
+        import "katex/dist/katex.min.css"
+        import "highlight.js/styles/${theme}.css"
+        ${mermaidCode}
+
+        export const metadata = ${JSON.stringify(data)}
+        
+        export default {
+          render() {
+            if (typeof window !== "undefined" && ${hasMermaid}) {
+              setTimeout(() => {
+                mermaid.run({ querySelector: ".mermaid" })
+              }, 0)
+            }
+            return html\`<div class="markdown-body">\${unsafeHTML(${JSON.stringify(htmlContent)})}</div>\`
+          }
+        }
+      `
+    },
+  }
+}

package/types/index.d.ts

@@ -1,280 +1,71 @@
-/**
- * Represents a page being built or processed.
- */
-export interface Page {
-  /**
-   * The final URL path for the page (e.g., "/about").
-   */
-  path: string
-  /**
-   * The route pattern that matched this page (e.g., "/posts/:id").
-   */
-  pattern: string
-  /**
-   * The absolute file path to the source component.
-   */
-  filePath: string
-  [key: string]: any
-}
+import type { UserConfig } from "vite"
 
-/**
- * Options passed to the layout function.
- */
-export interface LayoutOptions {
-  /**
-   * The language attribute for the <html> tag.
-   */
+export interface SiteConfig {
+  /** Site title */
+  title?: string
+  /** HTML lang attribute */
   lang?: string
-  /**
-   * The character encoding.
-   */
+  /** HTML charset */
   charset?: string
-  /**
-   * The page title.
-   */
-  title?: string
-  /**
-   * Meta tags to include in <head>.
-   */
+  /** Meta tags */
   meta?: Record<string, string>
-  /**
-   * Stylesheets to include.
-   */
+
+  /** Global styles to inject */
   styles?: string[]
-  /**
-   * Additional HTML to inject into <head>.
-   */
-  head?: string
-  /**
-   * Scripts to include.
-   */
+  /** Global scripts to inject */
   scripts?: string[]
-  /**
-   * Whether the build is running in development mode.
-   */
-  isDev?: boolean
-  [key: string]: any
-}
 
-/**
- * Configuration for the sitemap generation.
- */
-export interface SitemapConfig {
-  /**
-   * The base hostname for the sitemap URLs (e.g., "https://example.com").
-   */
-  hostname: string
-  /**
-   * A function to filter which pages are included in the sitemap.
-   */
-  filter?: (page: Page) => boolean
-  /**
-   * Default values for sitemap entries.
-   */
-  defaults?: {
-    /**
-     * How frequently the page is likely to change.
-     */
-    changefreq?: string
-    /**
-     * The priority of this URL relative to other URLs on your site.
-     */
-    priority?: number
-    /**
-     * The date of last modification.
-     */
-    lastmod?: string | Date
-  }
-}
+  /** Source root directory (default: "src") */
+  rootDir?: string
+  /** Output directory (default: "dist") */
+  outDir?: string
+  /** Public directory (default: "public") */
+  publicDir?: string
+  /** Base path for the site */
+  basePath?: string
+  /** Favicon path */
+  favicon?: string
 
-/**
- * Configuration for the RSS feed generation.
- */
-export interface RssConfig {
-  /**
-   * The title of the RSS feed.
-   */
-  title: string
-  /**
-   * The description of the RSS feed.
-   */
-  description: string
-  /**
-   * The link to the site associated with the feed.
-   */
-  link: string
-  /**
-   * The output path for the RSS feed file.
-   * @default "/feed.xml"
-   */
-  feedPath?: string
-  /**
-   * The language of the feed.
-   */
-  language?: string
-  /**
-   * Copyright notice for content in the feed.
-   */
-  copyright?: string
-  /**
-   * Maximum number of items to include in the feed.
-   */
-  maxItems?: number
-  /**
-   * A function to filter which pages are included in the feed.
-   */
-  filter?: (page: Page) => boolean
-}
+  /** Router configuration */
+  router?: {
+    trailingSlash?: boolean
+    scrollBehavior?: "auto" | "smooth"
+  }
 
-/**
- * Configuration for a URL redirect.
- */
-export interface RedirectConfig {
-  /**
-   * The source path or pattern to redirect from.
-   */
-  from: string
-  /**
-   * The destination path to redirect to.
-   */
-  to: string
-  /**
-   * The HTTP status code for the redirect.
-   * @default 301
-   */
-  status?: number
-}
+  /** Vite configuration */
+  vite?: UserConfig
 
-/**
- * Configuration for the client-side router.
- */
-export interface RouterConfig {
-  /**
-   * Whether to enforce trailing slashes on URLs.
-   */
-  trailingSlash?: boolean
-  /**
-   * The scroll behavior when navigating between pages.
-   */
-  scrollBehavior?: "auto" | "smooth"
-}
+  /** Markdown configuration */
+  markdown?: {
+    /** Highlight.js theme (default: "github-dark") */
+    theme?: string
+  }
 
-/**
- * Result object passed to the afterBuild hook.
- */
-export interface BuildResult {
-  /**
-   * The total number of pages generated.
-   */
-  pages: number
-  [key: string]: any
-}
+  /** Sitemap configuration */
+  sitemap?: {
+    hostname: string
+    filter?: (page: any) => boolean
+    defaults?: {
+      changefreq?: string
+      priority?: number
+    }
+  }
 
-/**
- * Lifecycle hooks for the build process.
- */
-export interface SSXHooks {
-  /**
-   * Called before the build process starts.
-   */
-  beforeBuild?: (config: SiteConfig) => Promise<void> | void
-  /**
-   * Called after the build process completes.
-   */
-  afterBuild?: (result: BuildResult) => Promise<void> | void
-  /**
-   * Called after an individual page is built.
-   */
-  onPageBuild?: (page: Page) => Promise<void> | void
-}
+  /** RSS configuration */
+  rss?: {
+    title: string
+    description: string
+    link: string
+    feedPath?: string
+    language?: string
+    copyright?: string
+    maxItems?: number
+    filter?: (page: any) => boolean
+  }
 
-/**
- * Main configuration object for SSX.
- */
-export interface SiteConfig {
-  /**
-   * The language attribute for the <html> tag.
-   * @default "en"
-   */
-  lang?: string
-  /**
-   * The character encoding for the site.
-   * @default "UTF-8"
-   */
-  charset?: string
-  /**
-   * The default title for pages.
-   */
-  title?: string
-  /**
-   * Default meta tags to be applied to all pages.
-   * Keys are meta names/properties, values are content.
-   */
-  meta?: Record<string, string>
-  /**
-   * List of CSS file paths or URLs to include globally.
-   */
-  styles?: string[]
-  /**
-   * List of JavaScript file paths or URLs to include globally.
-   */
-  scripts?: string[]
-  /**
-   * A function that renders the full HTML document structure.
-   * Receives the page body and options.
-   */
-  layout?: (body: string, options: LayoutOptions) => string
-  /**
-   * A function to wrap the page content before layout.
-   * Useful for adding common UI elements like headers/footers around the content.
-   */
-  wrapper?: (body: any) => any
-  /**
-   * The base URL path for the application.
-   * @default "/"
-   */
-  basePath?: string
-  /**
-   * The directory containing source files.
-   * @default "src"
-   */
-  rootDir?: string
-  /**
-   * The directory where build artifacts will be output.
-   * @default "dist"
-   */
-  outDir?: string
-  /**
-   * The directory containing static assets to be copied to the output.
-   * @default "public"
-   */
-  publicDir?: string
-  /**
-   * Path to the favicon file.
-   */
-  favicon?: string
-  /**
-   * Configuration for generating a sitemap.xml.
-   */
-  sitemap?: SitemapConfig
-  /**
-   * Configuration for generating an RSS feed.
-   */
-  rss?: RssConfig
-  /**
-   * List of redirect rules.
-   */
-  redirects?: RedirectConfig[]
-  /**
-   * Configuration for the client-side router.
-   */
-  router?: RouterConfig
-  /**
-   * Configuration options passed directly to Vite.
-   */
-  vite?: Record<string, any>
-  /**
-   * Lifecycle hooks for the build process.
-   */
-  hooks?: SSXHooks
+  /** Build hooks */
+  hooks?: {
+    beforeBuild?: (config: SiteConfig) => Promise<void> | void
+    afterBuild?: (result: any) => Promise<void> | void
+  }
 }