defuss-ssg 0.0.1

package/README.md

@@ -0,0 +1,289 @@
+<h1 align="center">
+
+<img src="assets/defuss_mascott.png" width="100px" />
+
+<p align="center">
+  <code>defuss-ssg</code>
+</p>
+
+<sup align="center">
+
+Simple Static Site Generator (SSG) for defuss - with support for Markdown, MDX, and Jinja2 templates
+
+</sup>
+
+</h1>
+
+<h3 align="center">
+Usage
+</h3>
+
+Simply generate a static site from a content directory to an output directory with full `defuss`-MDX (GFM + Frontmatter) support:
+
+```bash
+npx defuss-ssg build ./folder
+```
+
+Or install globally or locally in a project:
+
+```bash 
+npm install -g defuss-ssg
+```
+
+And then run (in an NPM script or globally):
+
+<h4>One-time builds</h4>
+
+```bash
+defuss-ssg build ./folder
+```
+
+<h4>Serve-mode with automatic re-build on change</h4>
+
+```bash
+defuss-ssg serve ./folder
+```
+
+This starts a local server at http://localhost:3000 and watches for changes in:
+
+- `pages/` directory
+- `components/` directory
+- `assets/` directory
+
+Changes trigger automatic rebuilds, with the last change always taking priority to prevent build queueing issues.
+
+<h4>Programmatic API</h4>
+
+Advanced users may want to use the library programmatically:
+
+```typescript
+import { build, serve } from "defuss-ssg";
+
+(async () => {
+  // One-time build
+  await build({
+    projectDir: "./my-site",
+    debug: true,
+  });
+
+  // Or serve with auto-rebuild
+  await serve({
+    projectDir: "./my-site", 
+    debug: true,
+  });
+})();
+```
+
+<h3 align="center">
+Overview
+</h3>
+
+> `defuss-ssg` is a CLI tool and library for building static websites using modern JavaScript/TypeScript and `defuss`. It reads content files (Markdown, MDX) from a specified directory, processes them with MDX plugins, compiles components with esbuild, and outputs fully static HTML sites ready for deployment.
+
+> It supports a plugin system for extending the build process at various phases (pre-build, post-build, page-level transformations), automatic file watching and rebuilding in serve mode, and seamless integration with defuss components for interactive features.
+
+<h3 align="center">
+
+Features
+
+</h3>
+
+- **MDX Support**: Full Markdown + JSX support with frontmatter parsing
+- **Component Integration**: Use defuss components in your MDX files
+- **Plugin System**: Extend the build process with custom plugins at multiple phases
+- **Fast Compilation**: Powered by esbuild for quick builds and hot reloading
+- **Serve Mode**: Built-in development server with file watching and auto-rebuild
+- **TypeScript Ready**: Full TypeScript support for components and configuration
+- **Asset Handling**: Automatic copying of static assets to output directory
+- **Flexible Configuration**: Configurable via TypeScript config file with sensible defaults
+
+<h3 align="center">
+
+Example site project structure
+
+</h3>
+
+Create a project structure like this:
+
+```typescript
+my-site/
+├── pages/
+│   ├── index.mdx
+│   └── blog/
+│       └── hello-world.mdx
+├── components/
+│   └── button.tsx
+├── assets/
+│   └── styles.css
+└── config.ts
+```
+Then run `defuss-ssg build ./my-site` and a `dist` folder will be created with the complete static build.
+
+<h3 align="center">
+
+Config file
+
+</h3>
+
+You can customize the paths and behaviour of the build process, by creating a simple `config.ts` file in the project folder.
+
+##### Example `config.ts` file
+
+```typescript
+import { remarkPlugins, rehypePlugins } from "defuss-ssg";
+
+export default {
+  pages: "pages",
+  output: "dist",
+  components: "components",
+  assets: "assets",
+  remarkPlugins: [...remarkPlugins], // default remark plugins
+  rehypePlugins: [...rehypePlugins], // default rehype plugins
+  plugins: [],
+};
+```
+
+You may add any `remark` and `rehype` plugin of your choice. See the `MDX` documentation for more informations on Remark and Rehype.
+
+`defuss-ssg` plugins can be registered via the `plugins` array and are executed in order of registration, in each build phase.
+
+##### Example MDX page (`pages/index.mdx`)
+
+```mdx
+---
+title: Home Page
+---
+
+import Button from "../components/button.js"
+
+# Welcome to my site
+
+This is a **markdown** page with JSX components.
+
+<Button>Click me</Button>
+```
+
+##### Example Button component (`components/button.tsx`)
+
+Components are imported as `.js` but saved as `.tsx`:
+
+```typescript
+export const Button = ({ label }: { label: string }) => {
+  return (
+    <button type="button" onClick={() => alert("Button clicked!")}>
+      {label}
+    </button>
+  );
+};
+```
+
+
+<h3 align="center">
+
+Plugin System
+
+</h3>
+
+Extend the build process with plugins that run at different phases:
+
+```typescript
+import { rule, transval, access } from 'defuss-transval';
+
+type UserData = {
+  user: {
+    profile: {
+      name: string;
+      email: string;
+      settings: {
+        theme: 'light' | 'dark';
+        notifications: boolean;
+      };
+    };
+    posts: Array<{
+      title: string;
+      published: boolean;
+    import { SsgPlugin } from "defuss-ssg";
+
+const myPlugin: SsgPlugin = {
+  name: "my-plugin",
+  phase: "page-html", // "pre" | "post" | "page-vdom" | "page-dom" | "page-html"
+  fn: (html, relativePath, config) => {
+    // Modify HTML before writing
+    return html.replace("old-text", "new-text");
+  },
+};
+
+export default {
+  plugins: [myPlugin],
+  // ... other config
+};
+```
+
+Available plugin phases:
+
+- **pre**: Before build starts
+- **page-vdom**: After VDOM creation for each page
+- **page-dom**: After DOM rendering for each page
+- **page-html**: After HTML serialization for each page
+- **post**: After build completes
+
+
+<h3 align="center">
+
+MDX Features
+
+</h3>
+
+`defuss-ssg` supports full MDX with `defuss` components and common GFM Markdown features:
+
+- **Frontmatter**: YAML/TOML metadata extraction - the `meta` object holds frontmatter data - use e.g. `{ meta.title }` for page title defined in frontmatter like this: 
+```mdx
+--- 
+title: My Page 
+---
+```
+
+- **JSX Components**: Use `defuss` components in your content
+- **Math Support**: KaTeX rendering with `$...$` and `$$...$$`
+- **Custom Plugins**: Extend MDX processing with remark/rehype plugins
+
+<h3 align="center">
+
+Build Process
+
+</h3>
+
+The build process follows these steps:
+
+1. **Copy Project**: Copy all files to temporary directory
+2. **Compile MDX**: Process MDX files to ESM JavaScript
+3. **Compile Components**: Bundle components with esbuild
+4. **Evaluate Pages**: Run page functions to generate VDOM
+5. **Render HTML**: Convert VDOM to HTML using defuss/server
+6. **Run Plugins**: Execute plugins at various phases
+7. **Copy Assets**: Copy static assets to output
+8. **Clean Up**: Remove temporary files (unless debug mode)
+
+<h3 align="center">
+
+CLI Reference 
+
+</h3>
+
+```bash
+defuss-ssg <command> <folder>
+
+Commands:
+  build <folder>    Build the static site
+  serve <folder>    Serve with auto-rebuild on changes
+```
+
+<p align="center">
+
+  <img src="https://raw.githubusercontent.com/kyr0/defuss/refs/heads/main/assets/defuss_comic.png" width="400px" />
+
+</p>
+
+<p align="center">
+  <i><b>Come visit us on <code>defuss</code> Island!</b></i>
+</p>

package/dist/cli.cjs

@@ -0,0 +1,47 @@
+'use strict';
+
+var serve = require('./serve-BaOtT5p7.cjs');
+var node_path = require('node:path');
+require('chokidar');
+require('express');
+require('serve-static');
+require('node:fs');
+require('esbuild');
+require('remark-frontmatter');
+require('rehype-katex');
+require('remark-math');
+require('remark-mdx-frontmatter');
+require('./tailwind-C4AuHybm.cjs');
+require('@mdx-js/esbuild');
+require('fast-glob');
+require('defuss/server');
+require('node:fs/promises');
+require('node:url');
+
+(async () => {
+  const args = process.argv.slice(2);
+  const command = args[0];
+  const folder = args[1];
+  const usage = "Usage: defuss-ssg <build|serve> <folder>";
+  if (!command || !folder) {
+    console.error(usage);
+    process.exit(1);
+  }
+  const projectDir = node_path.resolve(folder);
+  if (command === "build") {
+    console.log(`Building ${folder}...`);
+    await serve.build({
+      projectDir,
+      debug: true,
+      mode: "build"
+    });
+  } else if (command === "serve") {
+    console.log(`Serving ${folder}...`);
+    await serve.serve({
+      projectDir,
+      debug: true});
+  } else {
+    console.error(usage);
+    process.exit(1);
+  }
+})();

package/dist/cli.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import { d as build, s as serve } from './serve-COHw7ASj.mjs';
+import { resolve } from 'node:path';
+import 'chokidar';
+import 'express';
+import 'serve-static';
+import 'node:fs';
+import 'esbuild';
+import 'remark-frontmatter';
+import 'rehype-katex';
+import 'remark-math';
+import 'remark-mdx-frontmatter';
+import './tailwind-DV23JSh-.mjs';
+import '@mdx-js/esbuild';
+import 'fast-glob';
+import 'defuss/server';
+import 'node:fs/promises';
+import 'node:url';
+
+(async () => {
+  const args = process.argv.slice(2);
+  const command = args[0];
+  const folder = args[1];
+  const usage = "Usage: defuss-ssg <build|serve> <folder>";
+  if (!command || !folder) {
+    console.error(usage);
+    process.exit(1);
+  }
+  const projectDir = resolve(folder);
+  if (command === "build") {
+    console.log(`Building ${folder}...`);
+    await build({
+      projectDir,
+      debug: true,
+      mode: "build"
+    });
+  } else if (command === "serve") {
+    console.log(`Serving ${folder}...`);
+    await serve({
+      projectDir,
+      debug: true});
+  } else {
+    console.error(usage);
+    process.exit(1);
+  }
+})();

package/dist/components/index.cjs

@@ -0,0 +1,27 @@
+'use strict';
+
+var jsxRuntime = require('defuss/jsx-runtime');
+
+function Hydrate({
+  module,
+  exportName = "default",
+  props = {},
+  children
+}) {
+  const id = `dh_${Math.random().toString(36).slice(2)}`;
+  return /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+    children,
+    /* @__PURE__ */ jsxRuntime.jsx(
+      "div",
+      {
+        "data-hydrate": true,
+        "data-module": module,
+        "data-export": exportName,
+        "data-props-id": id
+      }
+    ),
+    /* @__PURE__ */ jsxRuntime.jsx("script", { type: "application/json", id, children: JSON.stringify(props) })
+  ] });
+}
+
+exports.Hydrate = Hydrate;

package/dist/components/index.d.cts

@@ -0,0 +1,10 @@
+import { Props } from 'defuss';
+
+interface HydrateProps extends Props {
+    module: string;
+    exportName?: string;
+    props?: Record<string, any>;
+}
+declare function Hydrate({ module, exportName, props, children, }: HydrateProps): any;
+
+export { Hydrate, type HydrateProps };

package/dist/components/index.d.mts

@@ -0,0 +1,10 @@
+import { Props } from 'defuss';
+
+interface HydrateProps extends Props {
+    module: string;
+    exportName?: string;
+    props?: Record<string, any>;
+}
+declare function Hydrate({ module, exportName, props, children, }: HydrateProps): any;
+
+export { Hydrate, type HydrateProps };

package/dist/components/index.mjs

@@ -0,0 +1,25 @@
+import { jsxs, Fragment, jsx } from 'defuss/jsx-runtime';
+
+function Hydrate({
+  module,
+  exportName = "default",
+  props = {},
+  children
+}) {
+  const id = `dh_${Math.random().toString(36).slice(2)}`;
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    children,
+    /* @__PURE__ */ jsx(
+      "div",
+      {
+        "data-hydrate": true,
+        "data-module": module,
+        "data-export": exportName,
+        "data-props-id": id
+      }
+    ),
+    /* @__PURE__ */ jsx("script", { type: "application/json", id, children: JSON.stringify(props) })
+  ] });
+}
+
+export { Hydrate };

package/dist/index.cjs

@@ -0,0 +1,28 @@
+'use strict';
+
+var serve = require('./serve-BaOtT5p7.cjs');
+require('chokidar');
+require('express');
+require('serve-static');
+require('node:path');
+require('node:fs');
+require('esbuild');
+require('remark-frontmatter');
+require('rehype-katex');
+require('remark-math');
+require('remark-mdx-frontmatter');
+require('./tailwind-C4AuHybm.cjs');
+require('@mdx-js/esbuild');
+require('fast-glob');
+require('defuss/server');
+require('node:fs/promises');
+require('node:url');
+
+
+
+exports.build = serve.build;
+exports.configDefaults = serve.configDefaults;
+exports.readConfig = serve.readConfig;
+exports.rehypePlugins = serve.rehypePlugins;
+exports.remarkPlugins = serve.remarkPlugins;
+exports.serve = serve.serve;

package/dist/index.d.cts

@@ -0,0 +1,25 @@
+import { R as RemarkPlugins, a as RehypePlugins, S as SsgConfig, B as BuildOptions } from './types-D1n7GtYH.js';
+export { e as BuildMode, f as PluginFn, c as PluginFnPageDom, P as PluginFnPageHtml, b as PluginFnPageVdom, d as PluginFnPrePost, g as SsgPlugin } from './types-D1n7GtYH.js';
+import '@mdx-js/esbuild';
+import 'defuss/server';
+
+declare const remarkPlugins: RemarkPlugins;
+declare const rehypePlugins: RehypePlugins;
+
+declare const readConfig: (projectDir: string, debug: boolean) => Promise<SsgConfig>;
+declare const configDefaults: SsgConfig;
+
+/**
+ * A single, complete build process for a static site project.
+ * @param projectDir The root directory of the project to build
+ */
+declare const build: ({ projectDir, debug, mode, }: BuildOptions) => Promise<void>;
+
+/**
+ * A simple static file server to serve the generated static site from the output folder.
+ * Also watches the input, components and assets folders for changes and rebuilds the site on-the-fly.
+ * @param projectDir The root directory of the project to build
+ */
+declare const serve: ({ projectDir, debug }: BuildOptions) => Promise<void>;
+
+export { BuildOptions, RehypePlugins, RemarkPlugins, SsgConfig, build, configDefaults, readConfig, rehypePlugins, remarkPlugins, serve };

package/dist/index.d.mts

@@ -0,0 +1,25 @@
+import { R as RemarkPlugins, a as RehypePlugins, S as SsgConfig, B as BuildOptions } from './types-D1n7GtYH.js';
+export { e as BuildMode, f as PluginFn, c as PluginFnPageDom, P as PluginFnPageHtml, b as PluginFnPageVdom, d as PluginFnPrePost, g as SsgPlugin } from './types-D1n7GtYH.js';
+import '@mdx-js/esbuild';
+import 'defuss/server';
+
+declare const remarkPlugins: RemarkPlugins;
+declare const rehypePlugins: RehypePlugins;
+
+declare const readConfig: (projectDir: string, debug: boolean) => Promise<SsgConfig>;
+declare const configDefaults: SsgConfig;
+
+/**
+ * A single, complete build process for a static site project.
+ * @param projectDir The root directory of the project to build
+ */
+declare const build: ({ projectDir, debug, mode, }: BuildOptions) => Promise<void>;
+
+/**
+ * A simple static file server to serve the generated static site from the output folder.
+ * Also watches the input, components and assets folders for changes and rebuilds the site on-the-fly.
+ * @param projectDir The root directory of the project to build
+ */
+declare const serve: ({ projectDir, debug }: BuildOptions) => Promise<void>;
+
+export { BuildOptions, RehypePlugins, RemarkPlugins, SsgConfig, build, configDefaults, readConfig, rehypePlugins, remarkPlugins, serve };

package/dist/index.mjs

@@ -0,0 +1,17 @@
+export { d as build, c as configDefaults, b as readConfig, a as rehypePlugins, r as remarkPlugins, s as serve } from './serve-COHw7ASj.mjs';
+import 'chokidar';
+import 'express';
+import 'serve-static';
+import 'node:path';
+import 'node:fs';
+import 'esbuild';
+import 'remark-frontmatter';
+import 'rehype-katex';
+import 'remark-math';
+import 'remark-mdx-frontmatter';
+import './tailwind-DV23JSh-.mjs';
+import '@mdx-js/esbuild';
+import 'fast-glob';
+import 'defuss/server';
+import 'node:fs/promises';
+import 'node:url';

package/dist/plugins/index.cjs

@@ -0,0 +1,8 @@
+'use strict';
+
+var tailwind = require('../tailwind-C4AuHybm.cjs');
+require('node:path');
+
+
+
+exports.tailwindPlugin = tailwind.tailwindPlugin;

package/dist/plugins/index.d.cts

@@ -0,0 +1,7 @@
+import { g as SsgPlugin, d as PluginFnPrePost } from '../types-D1n7GtYH.js';
+import '@mdx-js/esbuild';
+import 'defuss/server';
+
+declare const tailwindPlugin: SsgPlugin<PluginFnPrePost>;
+
+export { tailwindPlugin };

package/dist/plugins/index.d.mts

@@ -0,0 +1,7 @@
+import { g as SsgPlugin, d as PluginFnPrePost } from '../types-D1n7GtYH.js';
+import '@mdx-js/esbuild';
+import 'defuss/server';
+
+declare const tailwindPlugin: SsgPlugin<PluginFnPrePost>;
+
+export { tailwindPlugin };

package/dist/plugins/index.mjs

@@ -0,0 +1,2 @@
+export { t as tailwindPlugin } from '../tailwind-DV23JSh-.mjs';
+import 'node:path';

package/dist/runtime.cjs

@@ -0,0 +1,26 @@
+'use strict';
+
+var defuss = require('defuss');
+require('defuss/client');
+
+async function hydrateIslands() {
+  const nodes = defuss.$("[data-hydrate]");
+  await Promise.all(
+    Array.from(nodes).map(async (el) => {
+      const modPath = el.dataset.module;
+      const exportKey = el.dataset.export || "default";
+      const propsId = el.dataset.propsId;
+      JSON.parse(
+        document.getElementById(propsId).textContent || "{}"
+      );
+      const mod = await import(
+        /* @vite-ignore */
+        modPath
+      );
+      mod[exportKey];
+      el.previousElementSibling;
+    })
+  );
+}
+
+exports.hydrateIslands = hydrateIslands;

package/dist/runtime.d.cts

@@ -0,0 +1,3 @@
+declare function hydrateIslands(): Promise<void>;
+
+export { hydrateIslands };

package/dist/runtime.d.mts

@@ -0,0 +1,3 @@
+declare function hydrateIslands(): Promise<void>;
+
+export { hydrateIslands };

package/dist/runtime.mjs

@@ -0,0 +1,24 @@
+import { $ } from 'defuss';
+import 'defuss/client';
+
+async function hydrateIslands() {
+  const nodes = $("[data-hydrate]");
+  await Promise.all(
+    Array.from(nodes).map(async (el) => {
+      const modPath = el.dataset.module;
+      const exportKey = el.dataset.export || "default";
+      const propsId = el.dataset.propsId;
+      JSON.parse(
+        document.getElementById(propsId).textContent || "{}"
+      );
+      const mod = await import(
+        /* @vite-ignore */
+        modPath
+      );
+      mod[exportKey];
+      el.previousElementSibling;
+    })
+  );
+}
+
+export { hydrateIslands };