@rahuldshetty/inscribe 0.0.1

package/README.md

@@ -0,0 +1,65 @@
+<div align="center">
+  <img src="https://via.placeholder.com/150x150.png?text=Inscribe" alt="Inscribe Logo" width="120" />
+  <h1>Inscribe</h1>
+  <p><strong>A minimalist, high-performance Static Site Generator (SSG)</strong></p>
+  <p>
+    <img src="https://img.shields.io/badge/status-under%20development-orange" alt="Project Status" />
+    <img src="https://img.shields.io/badge/license-MIT-blue" alt="License" />
+    <img src="https://img.shields.io/badge/built%20with-Bun-black" alt="Built with Bun" />
+  </p>
+</div>
+
+---
+
+Inscribe is a modern static site generator built with **Bun**, **MDX**, and **Preact**. It's designed to be fast, simple, and developer-friendly, making it perfect for blogs, documentation, and personal portfolios.
+
+> [!IMPORTANT]
+> This project is currently **under active development**. Features and APIs are subject to change.
+
+## ✨ Features
+
+- [x] **CLI** – Simple commands to scaffold, develop, and build your site.
+- [x] **Dev Server** – Local development server with instant live reload.
+- [x] **MDX & Markdown** – Write content using powerful MDX and standard Markdown.
+- [ ] **Search** – Integrated full-text search.
+- [ ] **Themes** – Customizable and extensible theme system.
+- [ ] **Plugins** – Flexible plugin architecture for extending functionality.
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+# Using Bun (Recommended)
+bun install -g inscribe-ssg
+
+# Using npm
+npm install -g inscribe-ssg
+```
+
+### Usage
+
+Scaffold a new project, start the development server, or build for production.
+
+```bash
+# Initialize a new project in the current directory
+inscribe init
+
+# Run the development server with live reload
+inscribe dev
+
+# Build the static site for production
+inscribe build
+```
+
+## 🛠️ Commands
+
+| Command        | Description                                                     |
+| :------------- | :-------------------------------------------------------------- |
+| `init`         | Create a new scaffold for your blog or portfolio.               |
+| `dev [path]`   | Start the local development server (default: `.` port `3000`).  |
+| `build [path]` | Generate a production-ready static website (default: `./dist`). |
+
+---
+
+<p align="center">Made with ❤️ by <a href="https://github.com/rahuldshetty">rahuldshetty</a></p>

package/cli/api/builder.ts

@@ -0,0 +1,145 @@
+import fs from "fs-extra";
+import path from "path";
+import { minifyHtml } from "../utils/minifier";
+import { parseBlogPost, renderSectionPage, renderSectionIndexPage, renderHomePage, NavState } from "./renderer";
+import { Blog } from "../schemas/blog";
+import { InscribeConfig } from "../schemas/inscribe";
+import { readInscribeFile } from "./inscribe_reader";
+import { parseFolderMetadata } from "../utils/markdown";
+import { FolderMetadata } from "../schemas/folder";
+
+export interface BuildOptions {
+    sourceDir: string;
+    outputDir: string;
+    env: string;
+}
+
+const buildSection = async (
+    type: 'blog' | 'doc',
+    sourceDir: string,
+    outputDir: string,
+    files: string[],
+    isRelease: boolean,
+    inscribe: InscribeConfig,
+    navState: NavState
+): Promise<{ posts: Blog[]; folderMetadata: Record<string, FolderMetadata> }> => {
+    const posts: Blog[] = [];
+    const singularFolder = type === 'blog' ? 'blog' : 'doc';
+    const sectionRoot = path.join(sourceDir, type === 'doc' ? (inscribe.doc_path || 'docs') : (inscribe.blog_path || 'blog'));
+
+    await fs.ensureDir(path.join(outputDir, singularFolder));
+
+    const folderMetadata: Record<string, FolderMetadata> = {};
+
+    for (const filePath of files) {
+        if (filePath.endsWith("index.md")) {
+            const dir = path.dirname(filePath);
+            const relativeDir = path.relative(sectionRoot, dir);
+            folderMetadata[relativeDir || ''] = parseFolderMetadata(dir);
+            continue;
+        }
+
+        const post = await parseBlogPost(filePath);
+        (post as any).relativePath = path.relative(sectionRoot, filePath);
+        posts.push(post);
+    }
+
+    posts.sort((a, b) => {
+        const weightA = a.metadata.weight ?? 0;
+        const weightB = b.metadata.weight ?? 0;
+        if (weightA !== weightB) return weightA - weightB;
+        return a.metadata.slug.localeCompare(b.metadata.slug);
+    });
+
+    for (const post of posts) {
+        let fullHtml = await renderSectionPage(type, post, posts, folderMetadata, inscribe, sourceDir, navState);
+        if (isRelease) fullHtml = await minifyHtml(fullHtml);
+        await fs.writeFile(path.join(outputDir, singularFolder, `${post.metadata.slug}.html`), fullHtml);
+    }
+
+    return { posts, folderMetadata };
+}
+
+export async function build(options: BuildOptions) {
+    const { sourceDir, outputDir, env } = options;
+    const isRelease = env === "release";
+
+    // Read inscribe config
+    const inscribe = await readInscribeFile(sourceDir);
+
+    const blogPath = inscribe.blog_path === "null" || !inscribe.blog_path ? null : inscribe.blog_path;
+    const docPath = inscribe.doc_path === "null" || !inscribe.doc_path ? null : inscribe.doc_path;
+    const blogDir = blogPath ? path.join(sourceDir, blogPath) : null;
+    const docDir = docPath ? path.join(sourceDir, docPath) : null;
+
+    const hasBlog = blogDir ? fs.existsSync(blogDir) : false;
+    const hasDocs = docDir ? fs.existsSync(docDir) : false;
+    const hasHome = inscribe.show_home !== false;
+
+    if (!hasBlog && !hasDocs && !hasHome) {
+        throw new Error("At least one section (home, blog, or doc) must be active to generate the site.");
+    }
+
+    const navState: NavState = { hasHome, hasBlog, hasDocs };
+
+    // Ensure output directory exists
+    await fs.ensureDir(outputDir);
+
+    let redirectUrl = "";
+
+    // Build blogs
+    if (hasBlog && blogDir) {
+        const blogFiles = fs.readdirSync(blogDir, { recursive: true })
+            .filter((f): f is string => typeof f === "string" && (f.endsWith(".md") || f.endsWith(".mdx")))
+            .map((file) => path.join(blogDir, file));
+
+        console.log('No. of blog pages identified:', blogFiles.length);
+
+        const { posts: blogs } = await buildSection('blog', sourceDir, outputDir, blogFiles, isRelease, inscribe, navState);
+
+        await fs.ensureDir(path.join(outputDir, "blogs"));
+        let blogIndex = renderSectionIndexPage('blog', blogs, {}, inscribe, sourceDir, navState);
+        if (isRelease) blogIndex = await minifyHtml(blogIndex);
+        await fs.writeFile(path.join(outputDir, "blogs", "index.html"), blogIndex);
+
+        if (!redirectUrl) redirectUrl = "/blogs/";
+    }
+
+    // Build docs
+    if (hasDocs && docDir) {
+        const docFiles = fs.readdirSync(docDir, { recursive: true })
+            .filter((f): f is string => typeof f === "string" && (f.endsWith(".md") || f.endsWith(".mdx")))
+            .map((file) => path.join(docDir, file));
+
+        console.log('No. of doc pages identified:', docFiles.length);
+
+        // folderMetadata is computed once inside buildSection and reused for the index page
+        const { posts: docs, folderMetadata } = await buildSection('doc', sourceDir, outputDir, docFiles, isRelease, inscribe, navState);
+
+        await fs.ensureDir(path.join(outputDir, "docs"));
+        if (docs.length > 0) {
+            const firstLevelDoc = docs.find(p => !((p as any).relativePath).includes('/') && !((p as any).relativePath).includes('\\'));
+            const firstDocSlug = (firstLevelDoc || docs[0]).metadata.slug;
+            const redirectHtml = `<!DOCTYPE html><html><head><meta http-equiv="refresh" content="0; url=/doc/${firstDocSlug}"></head><body>Redirecting...</body></html>`;
+            await fs.writeFile(path.join(outputDir, "docs", "index.html"), redirectHtml);
+        }
+
+        if (!redirectUrl) redirectUrl = "/docs/";
+    }
+
+    // Generate index.html
+    let indexPage = "";
+    if (hasHome) {
+        indexPage = renderHomePage(inscribe, sourceDir, navState);
+    } else if (redirectUrl) {
+        indexPage = `<!DOCTYPE html><html><head><meta http-equiv="refresh" content="0; url=${redirectUrl}"></head><body>Redirecting...</body></html>`;
+    } else {
+        indexPage = `<!DOCTYPE html><html><body>No content available.</body></html>`;
+    }
+
+    if (isRelease && hasHome) {
+        indexPage = await minifyHtml(indexPage);
+    }
+
+    await fs.writeFile(path.join(outputDir, "index.html"), indexPage);
+}

package/cli/api/inscribe_reader.ts

@@ -0,0 +1,14 @@
+import fs from "fs-extra";
+import { parse as yamlParse } from 'yaml';
+import { InscribeSchema, InscribeConfig } from "../schemas/inscribe";
+import path from "path";
+
+export const readInscribeFile = async (rootDir: string): Promise<InscribeConfig> => {
+    const filePath = path.join(rootDir, "inscribe.yaml");
+    if (!fs.existsSync(filePath)) {
+        return InscribeSchema.parse({});
+    }
+    const content = fs.readFileSync(filePath, "utf-8");
+    const parsedYaml = yamlParse(content);
+    return InscribeSchema.parse(parsedYaml);
+}

package/cli/api/renderer.ts

@@ -0,0 +1,199 @@
+import fs from "fs-extra";
+import path from "path";
+import nunjucks from "nunjucks";
+import { markdown2HTML, parseFrontMatter } from "../utils/markdown";
+import { Blog, BlogScehma } from "../schemas/blog";
+import { InscribeConfig } from "../schemas/inscribe";
+import { resolveThemeCSS } from "./theme_resolver";
+
+export const parseBlogPost = async (filePath: string) => {
+    const content = fs.readFileSync(filePath, "utf-8");
+    const { data, body } = parseFrontMatter(content);
+    const isMDX = filePath.endsWith(".mdx");
+
+    // Validate with Zod
+    const validated = BlogScehma.parse({
+        metadata: data,
+        markdown: body,
+        isMDX
+    });
+
+    return validated;
+};
+
+/**
+ * Configure Nunjucks with a search path:
+ * 1. User project layouts
+ * 2. CLI built-in layouts
+ */
+const getRenderer = (sourceDir: string) => {
+    const userLayouts = path.resolve(sourceDir, "layouts");
+    const builtInLayouts = path.resolve(__dirname, "../../template/layouts");
+
+    const searchPaths = [userLayouts, builtInLayouts];
+
+    return new nunjucks.Environment(
+        new nunjucks.FileSystemLoader(searchPaths),
+        { autoescape: true }
+    );
+};
+
+import { FolderMetadata } from "../schemas/folder";
+
+export interface NavState {
+    hasHome: boolean;
+    hasBlog: boolean;
+    hasDocs: boolean;
+}
+
+export type SidebarItem = 
+    | { type: 'folder'; node: SidebarNode }
+    | { type: 'file'; post: Blog };
+
+export interface SidebarNode {
+    title: string;
+    path: string;
+    weight: number;
+    items: SidebarItem[];
+}
+
+const getSidebarTree = (posts: Blog[], folderMetadata: Record<string, FolderMetadata> = {}): SidebarNode[] => {
+    // Root node — holds top-level files and sub-folder nodes
+    const root: SidebarNode = { title: '', path: '', weight: 0, items: [] };
+
+    // Map from path string to its SidebarNode (for quick lookup)
+    const nodeMap = new Map<string, SidebarNode>();
+    nodeMap.set('', root);
+
+    // Helper: ensure all ancestor nodes exist for a given path
+    const ensureNode = (dirPath: string): SidebarNode => {
+        if (nodeMap.has(dirPath)) return nodeMap.get(dirPath)!;
+
+        // Ensure parent exists first
+        const parentPath = path.dirname(dirPath).replace(/\\/g, '/');
+        const parent = ensureNode(parentPath === '.' ? '' : parentPath);
+
+        const meta = folderMetadata[dirPath] || { title: path.basename(dirPath), weight: 0 };
+        const node: SidebarNode = {
+            title: meta.title || path.basename(dirPath),
+            path: dirPath,
+            weight: meta.weight || 0,
+            items: [],
+        };
+        nodeMap.set(dirPath, node);
+        parent.items.push({ type: 'folder', node });
+        return node;
+    };
+
+    // Place each post in the correct node
+    for (const post of posts) {
+        let dir = path.dirname((post as any).relativePath || '').replace(/\\/g, '/');
+        if (dir === '.') dir = '';
+        const node = ensureNode(dir);
+        node.items.push({ type: 'file', post });
+    }
+
+    // Recursively sort items within each node
+    const sortNode = (node: SidebarNode) => {
+        node.items.sort((a, b) => {
+            const wA = a.type === 'folder' ? a.node.weight : (a.post.metadata.weight ?? 0);
+            const wB = b.type === 'folder' ? b.node.weight : (b.post.metadata.weight ?? 0);
+            
+            if (wA !== wB) return wA - wB;
+            
+            const tA = a.type === 'folder' ? a.node.title : a.post.metadata.title;
+            const tB = b.type === 'folder' ? b.node.title : b.post.metadata.title;
+            return tA.localeCompare(tB);
+        });
+
+        for (const item of node.items) {
+            if (item.type === 'folder') {
+                sortNode(item.node);
+            }
+        }
+    };
+    sortNode(root);
+
+    return root.items.length > 0 ? [root] : [];
+};
+
+export const renderSectionPage = async (
+    type: 'blog' | 'doc',
+    post: Blog,
+    allPosts: Blog[],
+    folderMetadata: Record<string, FolderMetadata>,
+    inscribe: InscribeConfig,
+    sourceDir: string,
+    navState: NavState,
+    isDev: boolean = false
+) => {
+    const html = await markdown2HTML(post.markdown, post.isMDX);
+    const env = getRenderer(sourceDir);
+    const themeCSS = resolveThemeCSS(inscribe.theme ?? 'default', sourceDir);
+
+    const template = type === 'blog' ? "blog.njk" : "doc.njk";
+    
+    const sidebarTree = type === 'doc' ? getSidebarTree(allPosts, folderMetadata) : [];
+    const currentDirPath = path.dirname((post as any).relativePath || '').replace(/\\/g, '/').replace(/^\.$/, '');
+
+    return env.render(template, {
+        post, // rename to post instead of blog to be generic
+        allPosts,
+        sidebarTree,
+        currentDirPath,
+        blog: post,
+        doc: post,
+        config: inscribe,
+        content: html,
+        themeCSS,
+        navState,
+        isDev
+    });
+};
+
+export const renderSectionIndexPage = (
+    type: 'blog' | 'doc',
+    posts: Blog[],
+    folderMetadata: Record<string, FolderMetadata>,
+    inscribe: InscribeConfig,
+    sourceDir: string,
+    navState: NavState,
+    isDev: boolean = false
+) => {
+    const env = getRenderer(sourceDir);
+    const themeCSS = resolveThemeCSS(inscribe.theme ?? 'default', sourceDir);
+    
+    const template = type === 'blog' ? "blog_index.njk" : "doc_index.njk";
+    
+    const sidebarTree = type === 'doc' ? getSidebarTree(posts, folderMetadata) : [];
+
+    return env.render(template, {
+        posts, // rename to posts
+        allPosts: posts,
+        sidebarTree,
+        currentDirPath: '',
+        blogs: posts,
+        docs: posts,
+        config: inscribe,
+        themeCSS,
+        navState,
+        isDev
+    });
+};
+
+export const renderHomePage = (
+    inscribe: InscribeConfig,
+    sourceDir: string,
+    navState: NavState,
+    isDev: boolean = false
+) => {
+    const env = getRenderer(sourceDir);
+    const themeCSS = resolveThemeCSS(inscribe.theme ?? 'default', sourceDir);
+
+    return env.render("home.njk", {
+        config: inscribe,
+        themeCSS,
+        navState,
+        isDev
+    });
+};

package/cli/api/server.ts

@@ -0,0 +1,144 @@
+import fs from "fs-extra";
+import path from "path";
+import { parseBlogPost, renderSectionPage, renderSectionIndexPage, renderHomePage, NavState } from "./renderer";
+import { readInscribeFile } from "./inscribe_reader";
+import { parseFolderMetadata } from "../utils/markdown";
+import { Blog } from "../schemas/blog";
+
+export const LocalServer = (sourceDir: string, isDev: boolean = false, port = 3000) => {
+    return {
+        port: port,
+        async fetch(req: Request, server: any) {
+            const url = new URL(req.url);
+
+            // Handle WebSocket upgrade
+            if (isDev && url.pathname === "/_reload") {
+                const success = server.upgrade(req);
+                if (success) return undefined;
+            }
+
+            // Read inscribe config
+            const inscribe = await readInscribeFile(sourceDir);
+
+            const blogPath = inscribe.blog_path === "null" || !inscribe.blog_path ? null : inscribe.blog_path;
+            const docPath = inscribe.doc_path === "null" || !inscribe.doc_path ? null : inscribe.doc_path;
+            const blogDir = blogPath ? path.join(sourceDir, blogPath) : null;
+            const docDir = docPath ? path.join(sourceDir, docPath) : null;
+
+            const hasBlog = blogDir ? fs.existsSync(blogDir) : false;
+            const hasDocs = docDir ? fs.existsSync(docDir) : false;
+            const hasHome = inscribe.show_home !== false;
+            const navState: NavState = { hasHome, hasBlog, hasDocs };
+
+            // Helper: collect relative .md/.mdx file paths under a directory
+            const getFiles = (dir: string | null): string[] =>
+                dir && fs.existsSync(dir)
+                    ? (fs.readdirSync(dir, { recursive: true }) as string[]).filter(
+                          (f) => f.endsWith(".md") || f.endsWith(".mdx")
+                      )
+                    : [];
+
+            // Helper: parse all posts in a directory, attaching relativePath and sorting
+            const getAllPosts = async (dir: string, files: string[]): Promise<Blog[]> => {
+                const posts = await Promise.all(
+                    files
+                        .filter((f) => !f.endsWith("index.md"))
+                        .map(async (f) => {
+                            const post = await parseBlogPost(path.join(dir, f));
+                            (post as any).relativePath = f;
+                            return post;
+                        })
+                );
+                return posts.sort((a, b) => {
+                    const wA = a.metadata.weight ?? 0;
+                    const wB = b.metadata.weight ?? 0;
+                    if (wA !== wB) return wA - wB;
+                    return a.metadata.slug.localeCompare(b.metadata.slug);
+                });
+            };
+
+            // Helper: build folder-metadata map from index.md files
+            const getFolderMetadata = (dir: string, files: string[]): Record<string, any> => {
+                const meta: Record<string, any> = {};
+                for (const f of files) {
+                    if (f.endsWith("index.md")) {
+                        const absDir = path.dirname(path.join(dir, f));
+                        const relDir = path.relative(dir, absDir);
+                        meta[relDir.replace(/\\/g, '/') || ''] = parseFolderMetadata(absDir);
+                    }
+                }
+                return meta;
+            };
+
+            const blogFiles = getFiles(blogDir);
+            const docFilesRaw = getFiles(docDir);
+
+            // Home page
+            if (url.pathname === "/") {
+                if (hasHome) {
+                    const html = renderHomePage(inscribe, sourceDir, navState, isDev);
+                    return new Response(html, { headers: { "Content-Type": "text/html" } });
+                }
+                const redirectUrl = hasBlog ? "/blogs/" : hasDocs ? "/docs/" : "";
+                if (redirectUrl) return Response.redirect(`http://${url.host}${redirectUrl}`, 302);
+                return new Response("No content available", { status: 404 });
+            }
+
+            // Blogs index
+            if ((url.pathname === "/blogs" || url.pathname === "/blogs/") && hasBlog && blogDir) {
+                const blogs = await getAllPosts(blogDir, blogFiles);
+                const html = renderSectionIndexPage('blog', blogs, {}, inscribe, sourceDir, navState, isDev);
+                return new Response(html, { headers: { "Content-Type": "text/html" } });
+            }
+
+            // Docs index
+            if ((url.pathname === "/docs" || url.pathname === "/docs/") && hasDocs && docDir) {
+                const docs = await getAllPosts(docDir, docFilesRaw);
+                if (docs.length > 0) {
+                    const firstLevelDoc = docs.find(p => !((p as any).relativePath).includes('/') && !((p as any).relativePath).includes('\\'));
+                    const firstDocSlug = (firstLevelDoc || docs[0]).metadata.slug;
+                    return Response.redirect(`http://${url.host}/doc/${firstDocSlug}`, 302);
+                }
+                const docFolderMetadata = getFolderMetadata(docDir, docFilesRaw);
+                const html = renderSectionIndexPage('doc', docs, docFolderMetadata, inscribe, sourceDir, navState, isDev);
+                return new Response(html, { headers: { "Content-Type": "text/html" } });
+            }
+
+            // Blog page — match by frontmatter slug, not filename
+            if (url.pathname.startsWith("/blog/") && blogDir) {
+                const slug = url.pathname.replace("/blog/", "").replace(/\/$/, "");
+                const blogs = await getAllPosts(blogDir, blogFiles);
+                const blog = blogs.find((p) => p.metadata.slug === slug);
+                if (blog) {
+                    const fullHtml = await renderSectionPage('blog', blog, blogs, {}, inscribe, sourceDir, navState, isDev);
+                    return new Response(fullHtml, { headers: { "Content-Type": "text/html" } });
+                }
+            }
+
+            // Doc page — match by frontmatter slug, not filename
+            if (url.pathname.startsWith("/doc/") && docDir) {
+                const slug = url.pathname.replace("/doc/", "").replace(/\/$/, "");
+                const docs = await getAllPosts(docDir, docFilesRaw);
+                const docFolderMetadata = getFolderMetadata(docDir, docFilesRaw);
+                const doc = docs.find((p) => p.metadata.slug === slug);
+                if (doc) {
+                    const fullHtml = await renderSectionPage('doc', doc, docs, docFolderMetadata, inscribe, sourceDir, navState, isDev);
+                    return new Response(fullHtml, { headers: { "Content-Type": "text/html" } });
+                }
+            }
+
+            return new Response("Not Found", { status: 404 });
+        },
+        websocket: {
+            message(ws: any, message: string) { },
+            open(ws: any) {
+                ws.subscribe("reload");
+            },
+            close(ws: any) {
+                ws.unsubscribe("reload");
+            },
+        },
+    }
+}
+
+

package/cli/api/theme_resolver.ts

@@ -0,0 +1,31 @@
+import fs from "fs-extra";
+import path from "path";
+
+/**
+ * Resolves a theme name to its CSS content.
+ *
+ * Priority:
+ *   1. <sourceDir>/themes/<themeName>.css  (user override)
+ *   2. <builtInThemesDir>/<themeName>.css  (built-in preset)
+ *
+ * Throws a descriptive error if neither location has the file.
+ */
+export const resolveThemeCSS = (themeName: string, sourceDir: string): string => {
+    const userThemePath    = path.resolve(sourceDir, "themes", `${themeName}.css`);
+    const builtInThemePath = path.resolve(__dirname, "../../template/themes", `${themeName}.css`);
+
+    if (fs.existsSync(userThemePath)) {
+        return fs.readFileSync(userThemePath, "utf-8");
+    }
+
+    if (fs.existsSync(builtInThemePath)) {
+        return fs.readFileSync(builtInThemePath, "utf-8");
+    }
+
+    throw new Error(
+        `Theme "${themeName}" not found.\n` +
+        `  Checked: ${userThemePath}\n` +
+        `  Checked: ${builtInThemePath}\n` +
+        `  Place a "${themeName}.css" file in your project's "themes/" folder, or use a built-in theme name.`
+    );
+};